Copy page

Email verifiers

Migrate from Hunter (email verifier)

This guide maps the Hunter API v2 Email Verifier and Account endpoints to the Tomba Email Verifier. Hunter's Domain Search, Email Finder, and enrichment endpoints are covered in Migrate from Hunter (email finder). Hunter API behavior checked on 2026-09-29 against the Hunter API v2 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.hunter.io/v2 with https://api.tomba.io/v1.

Authentication changes

Hunter accepts the key as the api_key parameter, the X-API-KEY header, or a bearer token. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string:

Code
# Hunter
curl "https://api.hunter.io/v2/email-verifier?email=jane.doe@stripe.com" \
  -H "X-API-KEY: $HUNTER_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"

Tomba API keys expire; plan their rotation with Key expiry.

Parameter mapping

Response field mapping

Tomba nests the checks in data.email and returns the sources in data.sources. Field definitions are in Email verifier response.

Status mapping

Tomba has no webmail status: it checks webmail addresses like any other and sets the webmail field. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Hunter returns errors as an array of {id, code, details}. Tomba returns a single errors object with type, message, and code. The meaning of 403 and 429 also changes:

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

Bulk and async jobs

Hunter runs bulk Email Verifier lists from its dashboard, and its API endpoint takes one address per request. Tomba runs lists through the API as verifier bulk jobs: send a JSON list of addresses or a CSV file. See Email verifier.

Each job is created, launched, polled, and downloaded as CSV; see Lifecycle. A job is charged when you first download its results; see Billing.

Tomba's single-request endpoint never returns 202, so remove the retry loop you use for Hunter's Email Verifier.

Code example

This function replaces a call to Hunter's Email Verifier and returns Hunter's field names. 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,
};

async function emailVerifier(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 {
        status,
        result: check.result,
        score: check.score,
        email: check.email,
        regexp: check.regex,
        gibberish: check.gibberish,
        disposable: check.disposable,
        webmail: check.webmail,
        mx_records: check.mx_check,
        smtp_check: status === "valid",
        accept_all: check.accept_all,
        block: check.block,
        sources: (body.data.sources ?? []).map(
            ({ website_url, ...source }) => ({
                domain: website_url,
                ...source,
            }),
        ),
    };
}

console.log(await emailVerifier("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 api_key, X-API-KEY, or a bearer token.
2. Change the base URL and read the verifier fields under data.email.
3. Handle webmail addresses through the webmail field, compare status case-insensitively, and stop reading smtp_check as a mailbox result.
4. Swap error handling: 402 replaces Hunter's 429, 429 replaces Hunter's 403, 408 replaces 222, and errors is an object, not an array.
5. Remove the 202 polling loop.
6. Move list processing to verifier bulk jobs.
7. Verify the same sample of addresses with both services and compare the results before you switch production traffic.