Copy page

Email verifiers

Migrate from Clearout

This guide maps the Clearout API v2 email verification endpoints (instant verify, bulk verify, and available credits) to the Tomba Email Verifier and bulk verifier jobs. Clearout API behavior checked on 2026-09-30 against the Clearout API reference.

Before you begin

• Get your API key (ta_…) and secret (ts_…); see Authentication.
• Check what a verification costs in Credit costs and your plan's throttling in Limits by plan.
• Set your HTTP client timeout to at least 180 seconds. Tomba returns the finished result in the response.

Endpoint mapping

Replace the base URL https://api.clearout.io/v2 with https://api.tomba.io/v1. Clearout shows the base URL for your account's region under Developer, Reference in its app; replace that one if it differs.

Clearout's single-check endpoints (/email/verify/catchall, /disposable, /business, /free, /role, /gibberish) have no separate Tomba endpoints. The Email Verifier response carries accept_all, disposable, webmail, and gibberish for every address.

Authentication changes

Clearout reads an API token from the Authorization header. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

Code
# Clearout
curl -X POST "https://api.clearout.io/v2/email_verify/instant" \
  -H "Authorization: Bearer $CLEAROUT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@stripe.com"}'

# Tomba
curl "https://api.tomba.io/v1/email-verifier?email=jane.doe@stripe.com" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"

Tomba takes the address as a query parameter on a GET request, not in a JSON body. Tomba API keys expire; plan their rotation with Key expiry.

Parameter mapping

Response field mapping

Clearout returns the result in data. Tomba nests the checks in data.email and lists the public pages where the address appears in data.sources. Field definitions are in Email verifier response.

Tomba also returns score, accept_all, block, greylisted, regex, and whois, which have no field in Clearout's instant verify response. Read your remaining balance from the X-Verify-Remaining header or GET /v1/me; see Check usage.

Status mapping

Clearout documents four primary statuses. Its API returns them in data.status; the example response shows valid in lower case, so compare case-insensitively.

Tomba reports a disposable domain as its own status rather than as a flag next to a mailbox result. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Both APIs signal failures with HTTP status codes. Clearout's error body is {"status": …, "error": {"code", "message"}}; Tomba's is an errors object with type, message, and code.

Error responses don't consume credits. Every type is listed in Errors.

Bulk and async jobs

Code
curl -X POST "https://api.tomba.io/v1/bulk/verifier" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -F "name=Newsletter list" \
  -F "file=@emails.csv;type=text/csv" \
  -F "email_field_index=0"

The launch, progress, and download requests are shown in Lifecycle. Row limits and daily job limits are in Limits, and a job is charged when you first download its results; see Billing.

Code example

This function replaces a call to /email_verify/instant and returns Clearout's field names for the values Tomba supplies. It needs Node.js 18 or later.

Code
const TOMBA_HEADERS = {
    "X-Tomba-Key": process.env.TOMBA_API_KEY,
    "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
};

// Tomba status -> Clearout primary status, as Clearout's docs name them.
// Its API example returns "valid" in lower case; compare case-insensitively.
const STATUSES = {
    valid: "Valid",
    invalid: "Invalid",
    accept_all: "Catch All",
    unknown: "Unknown",
};

const yesNo = (value) => (value ? "yes" : "no");

async function instantVerify(email) {
    const url = new URL("https://api.tomba.io/v1/email-verifier");
    url.searchParams.set("email", email);
    const res = await fetch(url, { headers: TOMBA_HEADERS });
    const body = await res.json();
    if (body.errors) {
        throw new Error(
            `${res.status} ${body.errors.type}: ${body.errors.message}`,
        );
    }

    const check = body.data.email;
    const status = check.status.toLowerCase();
    return {
        email_address: check.email || email,
        // A disposable address has no mailbox status in Tomba.
        status: STATUSES[status] ?? "Unknown",
        disposable: yesNo(status === "disposable" || check.disposable),
        free: yesNo(check.webmail),
        gibberish: yesNo(check.gibberish),
        detail_info: {
            mx_record: check.mx?.records?.[0] ?? null,
            smtp_provider: check.smtp_provider,
        },
    };
}

console.log(await instantVerify("jane.doe@stripe.com"));

Cutover checklist

1. Store the Tomba key and secret as TOMBA_API_KEY and TOMBA_SECRET_KEY, and send them as X-Tomba-Key and X-Tomba-Secret instead of the Authorization header.
2. Change instant verification from a POST with a JSON body to GET https://api.tomba.io/v1/email-verifier?email=, drop timeout, and set a client timeout of at least 180 seconds.
3. Swap error handling: 422 for bad parameters, 402 for credits, 429 with Retry-After, and 408 and 451 as new cases.
4. Translate status with the status mapping, comparing it case-insensitively, and read disposable, webmail, and gibberish as booleans.
5. Replace bulk uploads with verifier bulk jobs: convert XLSX to CSV, launch, receive the webhook_url event instead of the webhook, and download the CSV.
6. Verify the same sample list with both services and compare the mapped results before you switch production traffic.