# Migrate from Kickbox to Tomba

This guide will help you seamlessly transition from Kickbox to Tomba's email verification service, offering superior data attributes, better pricing, and advanced features.

---

## Why Choose Tomba Over Kickbox?

| Feature                     | Kickbox         | Tomba                                     |
| --------------------------- | --------------- | ----------------------------------------- |
| **Accuracy**                | 95-98%          | 99%+                                      |
| **Pricing**                 | $0.01 per email | 20-25% more cost-effective                |
| **Data Attributes**         | 6-8 fields      | 15+ comprehensive attributes              |
| **Catchall Detection**      | Basic           | Advanced with confidence scoring          |
| **Speed**                   | Fast            | Ultra-fast with optimized infrastructure  |
| **Bulk Verification**       | Yes             | Yes, with better batch processing         |
| **API Access**              | REST API        | REST API + MCP integration                |
| **Smart Caching**           | No              | 3-month automatic caching (saves credits) |
| **SMTP Provider Detection** | No              | Advanced provider identification          |
| **Whois Data**              | No              | Comprehensive domain registration details |
| **Source Tracking**         | No              | URLs and timestamps for data provenance   |
| **AI Integration**          | No              | Model Context Protocol (MCP) support      |

---

## Key Advantages of Tomba

### 1. Superior Data Intelligence (15+ Attributes)

Tomba provides comprehensive verification data with 15+ attributes:

- **Verification Results**: `status` (valid/invalid/accept_all/etc.), `result` (deliverable/undeliverable/risky), `score` (0-100)
- **SMTP Intelligence**: `smtp_provider` (e.g., "Google Workspace"), `smtp_server`, `smtp_check`
- **MX Infrastructure**: Complete `mx.records` array, `mx_check` validation
- **Email Quality Signals**: `accept_all`, `greylisted`, `block`, `gibberish`, `regex`
- **Email Type Detection**: `disposable`, `webmail`
- **Domain Insights**: `whois` data including registrar, creation date, referral URL
- **Data Provenance**: `sources` array with URIs, extraction dates, and page status

**Example comprehensive response:**

```json
{
    "data": {
        "email": {
            "email": "dayna.winter@shopify.com",
            "result": "deliverable",
            "status": "valid",
            "score": 99,
            "smtp_provider": "Google Workspace",
            "mx": {
                "records": [
                    "aspmx.l.google.com",
                    "alt1.aspmx.l.google.com",
                    "alt2.aspmx.l.google.com",
                    "alt4.aspmx.l.google.com",
                    "alt3.aspmx.l.google.com"
                ]
            },
            "mx_check": true,
            "smtp_server": true,
            "smtp_check": true,
            "accept_all": true,
            "greylisted": false,
            "block": false,
            "gibberish": false,
            "disposable": false,
            "webmail": false,
            "regex": true,
            "whois": {
                "registrar_name": "markmonitor inc.",
                "referral_url": "http://www.markmonitor.com",
                "created_date": "2005-03-11T06:18:03+01:00"
            }
        },
        "sources": [
            {
                "uri": "https://www.shopify.com/blog/black-friday-cyber-monday-shopify-apps",
                "website_url": "www.shopify.com",
                "extracted_on": "2022-11-07T13:16:42+01:00",
                "last_seen_on": "2022-11-07T13:16:42+01:00",
                "still_on_page": true
            }
        ]
    }
}
```

### 2. Smart Caching System (Save 40-60% on Costs)

**Tomba's unique advantage**: Automatic 3-month verification caching

- Skip verification if email was checked within the last 3 months
- Free cached results (no credits charged)
- Instant response times for cached emails
- Automatic freshness management

**Cost savings example:**

- 10,000 monthly verifications
- 40% are repeat checks (CRM updates, follow-ups)
- Kickbox: $100/month (10,000 × $0.01)
- Tomba: $48/month (6,000 × $0.008, 4,000 cached = free)
- **Save $52/month = 52% savings!**

### 3. Better Pricing

- 20-25% lower cost per verification
- No monthly minimums
- Credits roll over indefinitely
- Volume discounts available
- Free cached verifications

### 4. Advanced Integration Options

- Official SDKs for 10+ languages
- Model Context Protocol (MCP) for AI tools
- Google Sheets add-on
- Microsoft Excel add-in
- Browser extensions (Chrome, Firefox, Edge, Safari)
- Zapier and n8n integrations

### 5. SMTP Provider Intelligence

Unlike Kickbox, Tomba identifies the actual email service provider:

- "Google Workspace"
- "Microsoft 365"
- "Zoho Mail"
- "ProtonMail"
- And 50+ other providers

This helps you:

- Segment contacts by provider
- Optimize email deliverability
- Identify corporate vs personal emails
- Enhance lead scoring

---

## Migration Steps

### Step 1: Get Your Tomba API Credentials

1. Sign up at [app.tomba.io](https://app.tomba.io)
2. Navigate to **API** → **API Keys**
3. Copy your **API Key** and **Secret Key**

### Step 2: Update API Endpoints

**Kickbox endpoint:**

```
GET https://api.kickbox.com/v2/verify?email={email}
```

**Tomba endpoint:**

```
GET https://api.tomba.io/v1/email-verifier?email={email}
```

### Step 3: Update Authentication

**Kickbox authentication:**

```javascript
{
  "headers": {
    "Authorization": "Bearer your_kickbox_key"
  }
}
```

**Tomba authentication:**

```javascript
{
  "headers": {
    "X-Tomba-Key": "your_api_key",
    "X-Tomba-Secret": "your_secret_key"
  }
}
```

### Step 4: Update Response Mapping

**Kickbox response:**

```json
{
    "result": "deliverable",
    "reason": "accepted_email",
    "role": false,
    "free": false,
    "disposable": false,
    "accept_all": false,
    "did_you_mean": null,
    "sendex": 1,
    "email": "test@example.com"
}
```

**Tomba response (with 15+ attributes):**

```json
{
    "data": {
        "email": "test@example.com",
        "status": "valid",
        "result": "deliverable",
        "score": 100,
        "smtp_provider": "Google Workspace",
        "mx": {
            "records": ["mx1.example.com", "mx2.example.com"]
        },
        "mx_check": true,
        "smtp_server": true,
        "smtp_check": true,
        "accept_all": false,
        "greylisted": false,
        "block": false,
        "disposable": false,
        "webmail": false,
        "gibberish": false,
        "regex": true,
        "whois": {
            "registrar_name": "google llc",
            "created_date": "1999-09-15T04:00:00+00:00"
        }
    }
}
```

---

## Code Migration Examples

### Node.js

**Before (Kickbox):**

```javascript
const axios = require("axios");

async function verifyEmail(email) {
    const response = await axios.get(
        `https://api.kickbox.com/v2/verify?email=${email}`,
        {
            headers: {
                Authorization: `Bearer ${process.env.KICKBOX_KEY}`,
            },
        },
    );

    return response.data;
}
```

**After (Tomba):**

```javascript
const axios = require("axios");

async function verifyEmail(email) {
    const response = await axios.get(`https://api.tomba.io/v1/email-verifier`, {
        params: { email: email },
        headers: {
            "X-Tomba-Key": process.env.TOMBA_KEY,
            "X-Tomba-Secret": process.env.TOMBA_SECRET,
        },
    });

    const data = response.data.data;

    // Access rich attributes not available in Kickbox
    console.log(`Status: ${data.status}`);
    console.log(`SMTP Provider: ${data.smtp_provider}`);
    console.log(`Score: ${data.score}`);
    console.log(`Whois: ${data.whois?.registrar_name}`);

    return data;
}
```

**Using Tomba SDK:**

```javascript
const Tomba = require("tomba") {4-5};

const client = new Tomba.Client()
    .setKey(process.env.TOMBA_KEY)
    .setSecret(process.env.TOMBA_SECRET);

const verifier = new Tomba.Verifier(client);

async function verifyEmail(email) {
    const result = await verifier.emailVerifier({ email: email });
    return result.data;
}
```

### Python

**Before (Kickbox):**

```python
import requests

def verify_email(email):
    response = requests.get(
        f'https://api.kickbox.com/v2/verify?email={email}',
        headers={'Authorization': f'Bearer {os.environ["KICKBOX_KEY"]}'}
    )
    return response.json()
```

**After (Tomba):**

```python
import requests

def verify_email(email):
    response = requests.get(
        'https://api.tomba.io/v1/email-verifier',
        params={'email': email},
        headers={
            'X-Tomba-Key': os.environ['TOMBA_KEY'],
            'X-Tomba-Secret': os.environ['TOMBA_SECRET']
        }
    )
    data = response.json()['data']

    # Access rich attributes
    print(f"Status: {data['status']}")
    print(f"SMTP Provider: {data.get('smtp_provider', 'N/A')}")
    print(f"Score: {data['score']}")
    print(f"Whois: {data.get('whois', {}).get('registrar_name', 'N/A')}")

    return data
```

**Using Tomba SDK:**

```python
from tomba import Client, Verifier

client = Client()
client.set_key(os.environ['TOMBA_KEY'])
client.set_secret(os.environ['TOMBA_SECRET'])

verifier = Verifier(client)

def verify_email(email):
    result = verifier.email_verifier(email=email)
    return result['data']
```

### PHP

**Before (Kickbox):**

```php
<?php
function verifyEmail($email) {
    $ch = curl_init('https://api.kickbox.com/v2/verify?email=' . urlencode($email));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $_ENV['KICKBOX_KEY']
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response);
}
```

**After (Tomba):**

```php
<?php
function verifyEmail($email) {
    $ch = curl_init('https://api.tomba.io/v1/email-verifier?email=' . urlencode($email));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Tomba-Key: ' . $_ENV['TOMBA_KEY'],
        'X-Tomba-Secret: ' . $_ENV['TOMBA_SECRET']
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response)->data;

    // Access rich attributes
    echo "Status: " . $data->status . "\n";
    echo "SMTP Provider: " . ($data->smtp_provider ?? 'N/A') . "\n";
    echo "Score: " . $data->score . "\n";
    echo "Whois: " . ($data->whois->registrar_name ?? 'N/A') . "\n";

    return $data;
}
```

**Using Tomba SDK:**

```php
<?php
require 'vendor/autoload.php';

use Tomba\Client;
use Tomba\Services\Verifier;

$client = new Client();
$client->setKey($_ENV['TOMBA_KEY'])
       ->setSecret($_ENV['TOMBA_SECRET']);

$verifier = new Verifier($client);

function verifyEmail($email) {
    global $verifier;
    $result = $verifier->emailVerifier(['email' => $email]);
    return $result['data'];
}
```

### Ruby

**Before (Kickbox):**

```ruby
require 'httparty'

def verify_email(email)
  response = HTTParty.get(
    "https://api.kickbox.com/v2/verify?email=#{email}",
    headers: { 'Authorization' => "Bearer #{ENV['KICKBOX_KEY']}" }
  )
  response.parsed_response
end
```

**After (Tomba):**

```ruby
require 'httparty'

def verify_email(email)
  response = HTTParty.get(
    "https://api.tomba.io/v1/email-verifier",
    query: { email: email },
    headers: {
      'X-Tomba-Key' => ENV['TOMBA_KEY'],
      'X-Tomba-Secret' => ENV['TOMBA_SECRET']
    }
  )

  data = response.parsed_response['data']

  # Access rich attributes
  puts "Status: #{data['status']}"
  puts "SMTP Provider: #{data['smtp_provider']}"
  puts "Score: #{data['score']}"

  data
end
```

---

## Status Mapping

| Kickbox Result  | Tomba Status | Tomba Result    | Notes                  |
| --------------- | ------------ | --------------- | ---------------------- |
| `deliverable`   | `valid`      | `deliverable`   | Direct mapping         |
| `undeliverable` | `invalid`    | `undeliverable` | Direct mapping         |
| `risky`         | `accept_all` | `risky`         | Catch-all or uncertain |
| `unknown`       | `unknown`    | `risky`         | Unable to verify       |

**Reason mapping:**

| Kickbox Reason       | Tomba Attributes                      |
| -------------------- | ------------------------------------- |
| `accepted_email`     | `status: valid`, `smtp_check: true`   |
| `rejected_email`     | `status: invalid`, `smtp_check: true` |
| `invalid_domain`     | `mx_check: false`                     |
| `invalid_email`      | `regex: false`                        |
| `low_quality`        | `score < 50`, `gibberish: true`       |
| `low_deliverability` | `accept_all: true`, `result: risky`   |

---

## Bulk Verification Migration

### Kickbox Bulk Process

```javascript
// Kickbox bulk verification (list-based)
const kickboxBulk = require("kickbox-bulk");

const client = new kickboxBulk.Client(process.env.KICKBOX_KEY);

// Upload list
const list = await client.createList("contacts.csv");

// Wait for processing...
```

### Tomba Bulk Process (Easier & Faster)

```javascript
// Tomba bulk verification (direct API)
const axios = require("axios");

const verifyBulk = async (emails) => {
    const response = await axios.post(
        "https://api.tomba.io/v1/bulk/email-verifier",
        { emails: emails },
        {
            headers: {
                "X-Tomba-Key": process.env.TOMBA_KEY,
                "X-Tomba-Secret": process.env.TOMBA_SECRET,
            },
        },
    );

    // Get results with webhook or polling
    return response.data;
};

// Example usage
verifyBulk(["test1@example.com", "test2@example.com", "test3@example.com"]);
```

**Key advantages:**

- Direct API call (no file uploads needed)
- Cached emails are free and instant
- Better error handling
- Real-time progress tracking

---

## Advanced Features

### 1. SMTP Provider Intelligence

```javascript
// Segment contacts by email provider
const data = await verifyEmail("test@example.com");

switch (data.smtp_provider) {
    case "Google Workspace":
        // Business email - high priority lead
        console.log("Corporate contact");
        break;
    case "Gmail":
        // Personal email - different approach
        console.log("Personal contact");
        break;
    case "Microsoft 365":
        // Enterprise contact
        console.log("Enterprise contact");
        break;
}
```

### 2. Source Tracking

```javascript
// Understand data provenance
const data = await verifyEmail("test@example.com");

if (data.sources && data.sources.length > 0) {
    data.sources.forEach((source) => {
        console.log(`Found on: ${source.uri}`);
        console.log(`Extracted: ${source.extracted_on}`);
        console.log(`Still active: ${source.still_on_page}`);
    });
}
```

### 3. Whois Domain Intelligence

```javascript
// Access domain registration data
const data = await verifyEmail("test@example.com");

if (data.whois) {
    console.log(`Registrar: ${data.whois.registrar_name}`);
    console.log(`Created: ${data.whois.created_date}`);
    console.log(`URL: ${data.whois.referral_url}`);

    // Calculate domain age
    const domainAge = new Date() - new Date(data.whois.created_date);
    const years = Math.floor(domainAge / (365 * 24 * 60 * 60 * 1000));
    console.log(`Domain age: ${years} years`);
}
```

### 4. Model Context Protocol (MCP)

Integrate with AI tools like Claude:

```json
// .claude/config.json
{
    "mcpServers": {
        "tomba": {
            "command": "npx",
            "args": ["-y", "@tomba-io/mcp"]
        }
    }
}
```

Now ask Claude: "Verify the email john@example.com and tell me about the company"

---

## Testing Your Migration

### Parallel Comparison Script

```javascript
const compareResults = async (testEmails) => {
    console.log("Email,Kickbox,Tomba,SMTP Provider,Score,Extra Data");

    for (const email of testEmails) {
        try {
            const [kickbox, tomba] = await Promise.all([
                verifyWithKickbox(email),
                verifyWithTomba(email),
            ]);

            console.log(
                `${email},${kickbox.result},${tomba.status},` +
                    `${tomba.smtp_provider},${tomba.score},` +
                    `"Whois: ${tomba.whois?.registrar_name || "N/A"}"`,
            );
        } catch (error) {
            console.error(`Error testing ${email}:`, error.message);
        }
    }
};

// Test with sample emails
compareResults([
    "test@shopify.com",
    "contact@microsoft.com",
    "invalid@example.com",
    "disposable@tempmail.com",
]);
```

### Cost Savings Calculator

```javascript
const calculateCostSavings = (monthlyVolume, repeatPercentage) => {
    const kickboxCost = monthlyVolume * 0.01;

    // Tomba: only pay for non-cached verifications
    const tombaNewChecks = monthlyVolume * (1 - repeatPercentage / 100);
    const tombaCost = tombaNewChecks * 0.008;

    const savings = kickboxCost - tombaCost;
    const savingsPercent = (savings / kickboxCost) * 100;

    console.log(`\n=== Cost Comparison ===`);
    console.log(`Monthly volume: ${monthlyVolume.toLocaleString()}`);
    console.log(`Repeat verifications: ${repeatPercentage}%`);
    console.log(`\nKickbox: $${kickboxCost.toFixed(2)}/month`);
    console.log(`Tomba: $${tombaCost.toFixed(2)}/month`);
    console.log(
        `\nSavings: $${savings.toFixed(2)}/month (${savingsPercent.toFixed(1)}%)`,
    );
    console.log(`Annual savings: $${(savings * 12).toFixed(2)}`);
};

// Examples
calculateCostSavings(10000, 40); // 10k emails, 40% cached
calculateCostSavings(50000, 35); // 50k emails, 35% cached
calculateCostSavings(100000, 50); // 100k emails, 50% cached
```

---

## Migration Checklist

- [ ] Sign up for Tomba account
- [ ] Generate API credentials (key + secret)
- [ ] Install Tomba SDK (optional but recommended)
- [ ] Update API endpoints in codebase
- [ ] Update authentication method (Bearer → X-Tomba-Key/Secret)
- [ ] Update response parsing to handle new structure
- [ ] Leverage new attributes (smtp_provider, whois, sources)
- [ ] Test with parallel verification (Kickbox vs Tomba)
- [ ] Update bulk verification code
- [ ] Update error handling
- [ ] Monitor cost savings from caching
- [ ] Update documentation
- [ ] Train team on new features
- [ ] Decommission Kickbox integration

---

## Support and Resources

- [Tomba API Documentation](https://docs.tomba.io)
- [Email Verifier Attributes](https://docs.tomba.io/attributes/verifier)
- [Bulk Verification Guide](https://docs.tomba.io/bulks/email-verifier)
- [SDKs and Libraries](https://docs.tomba.io/libraries)
- [MCP Integration Guide](https://docs.tomba.io/llm)
- [Support Portal](https://help.tomba.io)

Need help with migration? Contact our support team for personalized assistance.

---

## FAQ

**Q: Will I lose any features by switching from Kickbox?**
A: No! Tomba provides all Kickbox features plus 15+ data attributes, smart caching, SMTP provider detection, whois data, source tracking, and MCP integration.

**Q: How much can I save with Tomba's caching?**
A: With 40% repeat verifications (typical for CRM), you can save 40-50% on costs. For 10k monthly verifications, that's ~$50/month or $600/year in savings.

**Q: What is the SMTP provider feature?**
A: Tomba identifies the actual email service provider (Google Workspace, Microsoft 365, etc.). This helps you segment contacts, optimize deliverability, and enhance lead scoring.

**Q: Can I access domain registration data?**
A: Yes! Tomba includes whois data (registrar, creation date, URL) for every verified email, helping you assess domain age and legitimacy.

**Q: How does source tracking work?**
A: When available, Tomba provides URLs where the email was found, along with extraction dates and page status. This gives valuable context about your contacts.

**Q: Is migration difficult?**
A: No! Most migrations take 1-2 hours. The API structure is similar, and our SDKs make it even easier. We also provide migration support for enterprise customers.

**Q: Can I test before migrating?**
A: Yes! Sign up for a free account with 25 verifications to test the service and compare results side-by-side with Kickbox.

**Q: What about my existing Kickbox credits?**
A: Plan your transition timing to use remaining Kickbox credits, then switch to Tomba for ongoing verification needs.

**Q: Do you offer volume discounts?**
A: Yes! Contact our sales team for custom pricing on high-volume plans.

**Q: How does MCP integration work?**
A: MCP allows AI tools like Claude to directly access Tomba's verification. Just configure the MCP server and ask Claude to verify emails naturally in conversation.