Copy page

Email verifiers

Migrate from Bouncer

This guide maps the Bouncer API v1.1 (real-time verification, batch verification, and credits) to the Tomba Email Verifier and bulk verifier jobs. Bouncer API behavior checked on 2026-09-29 against the Bouncer API documentation.

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 host api.usebouncer.com with api.tomba.io.

Authentication changes

Bouncer reads the key from the x-api-key header or from basic authentication. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

Code
# Bouncer
curl "https://api.usebouncer.com/v1.1/email/verify?email=jane.doe@stripe.com" \
  -H "x-api-key: $BOUNCER_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

Bouncer returns a flat object whose flags are the strings yes, no, and unknown. Tomba nests the checks in data.email, uses booleans, and lists the public pages where the address appears in data.sources. Field definitions are in Email verifier response.

Tomba also returns block, gibberish, regex, and whois, which have no Bouncer counterpart.

Status mapping

Branch on status rather than result: Tomba's unknown status carries the result risky, and a disposable address has an empty result. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Bouncer's error body has status, error, and message; Tomba's errors object has 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.1/email/verify and returns Bouncer's field names, with yes and no flags. 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 -> Bouncer status
const STATUSES = {
    valid: "deliverable",
    accept_all: "risky",
    disposable: "risky",
    invalid: "undeliverable",
    unknown: "unknown",
};

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

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) {
        throw new Error(
            `${res.status} ${body.errors.type}: ${body.errors.message}`,
        );
    }

    const check = body.data.email;
    return {
        email: check.email || email,
        status: STATUSES[check.status.toLowerCase()] ?? "unknown",
        domain: {
            acceptAll: yesNo(check.accept_all),
            disposable: yesNo(check.disposable),
            free: yesNo(check.webmail),
        },
        provider: check.smtp_provider,
        score: check.score,
    };
}

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, and send them as X-Tomba-Key and X-Tomba-Secret instead of x-api-key.
2. Point single verifications at GET https://api.tomba.io/v1/email-verifier, drop timeout, and set a client timeout of at least 180 seconds.
3. Read results from data.email, convert yes/no flag checks to booleans, and translate status and reason with the status mapping.
4. Handle 402 and 429 as before, add 451 and 408, and treat an empty data array as an unknown job.
5. Replace batches with verifier bulk jobs: create, launch, poll /progress instead of using callback, and download the CSV.
6. Verify the same sample list with both services and compare the mapped results before you switch production traffic.