Copy page

Email verifiers

Migrate from Emailable

This guide maps the Emailable API v1 (single verification, batch verification, and account info) to the Tomba Email Verifier and bulk verifier jobs. Emailable API behavior checked on 2026-09-30 against the Emailable 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, so there is no 249 response to retry.

Endpoint mapping

Replace the base URL https://api.emailable.com/v1 with https://api.tomba.io/v1.

Authentication changes

Emailable reads the key from the api_key parameter (or an OAuth access_token), or from an Authorization: Bearer header. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string or body:

Code
# Emailable
curl "https://api.emailable.com/v1/verify?email=jane.doe@stripe.com" \
  -H "Authorization: Bearer $EMAILABLE_API_KEY"

# 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"

If you call Emailable from browser code with a public API key, move the call to your server and keep the Tomba key and secret there (Security). Tomba API keys expire; plan their rotation with Key expiry.

Parameter mapping

Response field mapping

Emailable returns a flat object. 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 block, greylisted, gibberish, regex, and whois, which have no Emailable counterpart. Read your remaining balance, Emailable's available_credits, from the X-Verify-Remaining header or GET /v1/me; see Check usage.

Status mapping

An address that Emailable returns as undeliverable with the reason invalid_email fails syntax checks; Tomba rejects it with 422 params_invalid instead of returning a status.

Tomba's result uses the same words as Emailable's state for deliverable, undeliverable, and risky, but an inconclusive check is risky, not unknown. Branch on status to tell them apart, and compare it case-insensitively. Each value is defined in Status values.

Error mapping

Both APIs signal failures with HTTP status codes. Emailable's error body is {"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" \
  -H "Content-Type: application/json" \
  -d '{"name": "Newsletter list", "list": "jane.doe@stripe.com\njohn.smith@shopify.com"}'

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 /v1/verify and returns Emailable'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 -> Emailable state
const STATES = {
    valid: "deliverable",
    invalid: "undeliverable",
    accept_all: "risky",
    disposable: "risky",
    unknown: "unknown",
};

async function verify(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) {
        // Tomba never returns 249; a response is always final.
        throw new Error(
            `${res.status} ${body.errors.type}: ${body.errors.message}`,
        );
    }

    const check = body.data.email;
    return {
        email: check.email || email,
        state: STATES[check.status.toLowerCase()] ?? "unknown",
        score: check.score,
        accept_all: check.accept_all,
        disposable: check.disposable,
        free: check.webmail,
        mx_record: check.mx?.records?.[0] ?? null,
        smtp_provider: check.smtp_provider,
    };
}

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

Cutover checklist

1. Store the Tomba key and secret as TOMBA_API_KEY and TOMBA_SECRET_KEY, send them as X-Tomba-Key and X-Tomba-Secret, and remove api_key and bearer tokens from your requests and logs.
2. Point single verifications at GET https://api.tomba.io/v1/email-verifier, drop smtp, accept_all, and timeout, and set a client timeout of at least 180 seconds.
3. Remove the 249 retry loop and swap error handling: 400 for a missing key, 401 for a wrong one, 422 for bad parameters, and 408 and 451 as new cases.
4. Translate state with the status mapping, branching on status rather than result, and compare it case-insensitively.
5. Replace batches with verifier bulk jobs: create with list or file, launch, receive the webhook_url event instead of the url callback, and download the CSV.
6. Verify the same sample list with both services and compare the mapped results before you switch production traffic.