Copy page

Email verifiers

Migrate from ZeroBounce

This guide maps the ZeroBounce API v2 (single validation, batch validation, the bulk file API, and credit balance) to the Tomba Email Verifier and bulk verifier jobs. ZeroBounce API behavior checked on 2026-09-30 against the ZeroBounce 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

ZeroBounce uses the hosts api.zerobounce.net (or api-us, api-eu) and bulkapi.zerobounce.net. Tomba serves everything from api.tomba.io.

Authentication changes

ZeroBounce reads the key from the api_key parameter, in the query string or the request body. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string or body:

Code
# ZeroBounce
curl "https://api.zerobounce.net/v2/validate?api_key=$ZEROBOUNCE_API_KEY&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 API keys expire; plan their rotation with Key expiry.

Parameter mapping

Response field mapping

ZeroBounce 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 score, block, greylisted, gibberish, regex, and whois, which have no ZeroBounce counterpart. Read your remaining balance from the X-Verify-Remaining header or GET /v1/me; see Check usage.

Status mapping

ZeroBounce returns some catch-all domains as valid with the accept_all sub-status. Tomba sets status to accept_all whenever the domain's mail server accepts mail for any address. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

ZeroBounce reports failures in the body: an error string on single validation and credits, an errors array on batch validation, and success: false with error_message on the file endpoints. Tomba returns an HTTP error status with an errors object, so check the status code instead:

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

Bulk and async jobs

ZeroBounce's validatebatch returns results in the response. Tomba runs every list as an asynchronous verifier bulk job, so move batch calls to the same flow as your file uploads, or send one GET /v1/email-verifier request per address.

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"

Tomba treats the first row of the file as a header, so add one if your ZeroBounce files have none. 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 /v2/validate and returns ZeroBounce'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 -> ZeroBounce [status, sub_status]
const STATUSES = {
    valid: ["valid", ""],
    invalid: ["invalid", ""],
    accept_all: ["catch-all", ""],
    unknown: ["unknown", ""],
    disposable: ["do_not_mail", "disposable"],
};

async function validate(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) {
        // Unlike ZeroBounce, errors use HTTP status codes, such as 402 or 429.
        throw new Error(
            `${res.status} ${body.errors.type}: ${body.errors.message}`,
        );
    }

    const check = body.data.email;
    const [status, sub_status] =
        STATUSES[check.status.toLowerCase()] ?? STATUSES.unknown;
    return {
        address: check.email || email,
        status,
        sub_status,
        free_email: check.webmail,
        catchall_domain: check.accept_all,
        mx_found: check.mx_check,
        mx_record: check.mx?.records?.[0] ?? null,
        smtp_provider: check.smtp_provider,
    };
}

console.log(await validate("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 from your URLs, request bodies, and logs.
2. Point single validations at GET https://api.tomba.io/v1/email-verifier, drop timeout, and set a client timeout of at least 180 seconds.
3. Replace checks of the error field with HTTP status handling: 402, 422, 429 with Retry-After, 408, and 451.
4. Translate status with the status mapping, comparing it case-insensitively, and stop branching on sub_status.
5. Replace validatebatch and sendfile with verifier bulk jobs: create, launch, receive the webhook_url event instead of return_url, and download the CSV.
6. Verify the same sample list with both services and compare the mapped results before you switch production traffic.