Copy page

Email verifiers

Migrate from DeBounce

This guide maps the DeBounce API v1 (single validation, bulk upload and status, and balance) to the Tomba Email Verifier and bulk verifier jobs. DeBounce API behavior checked on 2026-09-30 against the DeBounce API reference and its result codes.

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. Tomba throttles by requests per time window, not by concurrent calls.
• Set your HTTP client timeout to at least 180 seconds. Tomba returns the finished result in the response.

Endpoint mapping

DeBounce uses two hosts, api.debounce.io and bulk.debounce.io. Tomba serves everything from api.tomba.io.

Authentication changes

DeBounce reads the key from the api query parameter. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string:

Code
# DeBounce
curl "https://api.debounce.io/v1/?api=$DEBOUNCE_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"

If you call DeBounce from browser code with a public_ 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

DeBounce returns the result in a debounce object, with booleans and numbers as strings. Tomba nests the checks in data.email, uses JSON booleans, 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, gibberish, disposable, mx_check, mx.records, smtp_provider, regex, and whois, which have no field in DeBounce's response.

Status mapping

DeBounce reports role accounts in the role field rather than as code 8 in API responses; Tomba has no role flag. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Both APIs signal failures with HTTP status codes. DeBounce's error body is {"debounce": {"error", "code"}, "success": "0"}; 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"

Tomba treats the first row of the file as a header. A DeBounce list with one address per line and no header loses its first address, so add a header row first. 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 api.debounce.io/v1/ and returns DeBounce's code and reason for the address. 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 -> DeBounce [code, reason]
const CODES = {
    disposable: ["3", "Disposable"],
    accept_all: ["4", "Accept-All"],
    valid: ["5", "Deliverable"],
    invalid: ["6", "Invalid"],
    unknown: ["7", "Unknown"],
};

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) {
        // A malformed address (DeBounce code 1) fails with 422 params_invalid.
        throw new Error(
            `${res.status} ${body.errors.type}: ${body.errors.message}`,
        );
    }

    const check = body.data.email;
    const [code, reason] = CODES[check.status.toLowerCase()] ?? CODES.unknown;
    return {
        email: check.email || email,
        code,
        reason,
        free_email: String(check.webmail),
    };
}

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 the api parameter from your URLs and logs.
2. Point single validations at GET https://api.tomba.io/v1/email-verifier and set a client timeout of at least 180 seconds.
3. Replace checks of success with HTTP status handling: 402, 422, 429 with Retry-After, 408, and 451.
4. Translate code with the status mapping, comparing status case-insensitively, and read Tomba's booleans as JSON booleans rather than strings.
5. Replace URL uploads with verifier bulk jobs: upload the CSV with a header row, launch, poll /progress, and download the CSV.
6. Verify the same sample list with both services and compare the mapped results before you switch production traffic.