TombaTomba
Start free
  • Documentation
  • API reference
  • SDKs & CLI
  • AI & MCP
  • Integrations
  • Enterprise
  • Migration guides

Find, verify and enrich B2B contacts from public sources, in the app, your spreadsheet or through the API.

GDPR & CCPA

// docs

  • API changelog
  • Support options
  • Security

// platform

  • Dashboard
  • Pricing
  • API status

// resources

  • Help center
  • Product updates
  • TombaBot crawler

// company

  • Website
  • Contact us
  • Edit or remove your data

© 2021–2026 Tomba.io

  • Terms of service
  • Privacy policy
  • Cookie policy
  • Security policy
  • GDPR
  • CCPA
Clearbit
Email verifiers
    OverviewNeverBounceMillionVerifierBounceBanBouncerKickboxHunterZeroBounceEmailableClearoutDeBounce
Email finders
Phone finders
Email verifiers

Migrate from BounceBan

This guide maps the BounceBan v1 API (single verification, status polling, bulk tasks, and account) to the Tomba Email Verifier and bulk verifier jobs. BounceBan API behavior checked on 2026-09-29 against the BounceBan 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 to the first request.

Endpoint mapping

Replace the host api.bounceban.com (and api-waterfall.bounceban.com) with api.tomba.io.

BounceBanTomba
GET /v1/verify/singleGET /v1/email-verifier
GET /v1/verify/single on the waterfall hostGET /v1/email-verifier
GET /v1/verify/single/statusNo equivalent. The first response is final.
POST /v1/verify/bulk, POST /v1/verify/bulk/filePOST /v1/bulk/verifier, then PUT /v1/bulk/verifier/{id} to launch
GET /v1/verify/bulk/statusGET /v1/bulk/verifier/{id}/progress
GET /v1/verify/bulk/dump, POST /v1/verify/bulk/exportGET /v1/bulk/verifier/{id}/download (CSV)
POST /v1/verify/bulk/emailsNo equivalent. Download the job's CSV.
POST /v1/verify/bulk/destroyDELETE /v1/bulk/verifier/{id}/delete
GET /v1/accountGET /v1/me

Authentication changes

BounceBan reads the key from the Authorization header. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

TerminalCode
# BounceBan curl "https://api.bounceban.com/v1/verify/single?email=jane.doe@stripe.com" \ -H "Authorization: $BOUNCEBAN_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

BounceBanTombaNotes
emailemailRequired. A malformed address returns 422 params_invalid instead of a result.
urlwebhook_urlTomba still returns the result in the response, and also posts it to your URL when the result qualifies. See Per-request callbacks.
modeNo equivalent
disable_catchall_verifyNo equivalent
timeout (waterfall host)No equivalentSet the timeout in your HTTP client.
id (status endpoint)No equivalent

Response field mapping

BounceBan 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.

BounceBanTombaNotes
idNo equivalent
statusNo equivalentTomba has no verifying or queue state.
try_again_atNo equivalent
emaildata.email.emailAn empty string when the domain is disposable.
resultdata.email.result, data.email.statusSee Status mapping.
scoredata.email.scoreComputed differently. Recalibrate any threshold you apply to it.
is_disposabledata.email.disposable
is_accept_alldata.email.accept_all
is_roleNo equivalent
is_freedata.email.webmail
mx_recordsdata.email.mx.recordsdata.email.mx_check is true when the domain has MX records.
smtp_providerdata.email.smtp_provider
modeNo equivalent
verify_atNo equivalent
credits_consumed, credits_remainingX-Verify-Remaining header, GET /v1/meSee Check usage.

Tomba also returns block, greylisted, gibberish, regex, smtp_check, and whois, which have no BounceBan counterpart.

Status mapping

BounceBan resultTomba statusTomba result
deliverablevaliddeliverable
riskyaccept_allrisky
undeliverableinvalidundeliverable
unknownunknownrisky
Reported with is_disposable: truedisposableEmpty string

Branch on status, not 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

BounceBanTombaWhat to do
400 invalid parameter422 params_invalidFix the parameter named in the message.
401 missing or invalid key400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
403 insufficient credits402 quota_exceededWait for your usage window to renew or add credits.
405 account blocked401 or 403 authentication_failedContact support.
408 waterfall timeout408 proxy_errorThe mailbox check failed. Retry later.
429 rate limited429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
No equivalent451 claimed_emailThe owner of the address asked Tomba to stop processing it. Remove it from your list.
500500 api_errorRetry with backoff.

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

Bulk and async jobs

Tomba answers a single verification synchronously, so remove any polling of /v1/verify/single/status. For lists, run a bulk job of type verifier:

BounceBan stepTomba step
Create a task with emails or a CSV filePOST /v1/bulk/verifier with name and a newline-separated list, or a CSV file. Send BounceBan's email_column as email_field_index: both are zero-based.
Task starts on creationLaunch it: PUT /v1/bulk/verifier/{id}
GET /v1/verify/bulk/status, or the bulk.task_finished webhookPoll GET /v1/bulk/verifier/{id}/progress until status is completed, or set webhook_url to receive a bulk.completed event.
Dump or export resultsGET /v1/bulk/verifier/{id}/download?file=full. file=valid returns only valid rows.
TerminalCode
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 verifies one address with Tomba and returns it in BounceBan's shape, so code that reads BounceBan results keeps working. 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 -> BounceBan result. Disposable addresses count as undeliverable. const RESULTS = { valid: "deliverable", accept_all: "risky", invalid: "undeliverable", unknown: "unknown", disposable: "undeliverable", }; 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, result: RESULTS[check.status.toLowerCase()] ?? "unknown", score: check.score, is_disposable: check.disposable, is_accept_all: check.accept_all, is_free: check.webmail, mx_records: check.mx?.records ?? [], 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, and send them as X-Tomba-Key and X-Tomba-Secret instead of Authorization.
  2. Point single verifications at GET https://api.tomba.io/v1/email-verifier and remove status polling and try_again_at handling.
  3. Read results from data.email and translate them with the status mapping, comparing status case-insensitively.
  4. Handle 402 where you handled 403, retry 429 after Retry-After, and drop addresses that return 451.
  5. Replace bulk tasks with verifier jobs: create, launch, poll /progress, and download the CSV. Send email_column as email_field_index.
  6. Verify the same sample list with both services and compare the mapped results before you switch production traffic.
Last modified on November 6, 2026
MillionVerifierBouncer
On this page
  • Before you begin
  • Endpoint mapping
  • Authentication changes
  • Parameter mapping
  • Response field mapping
  • Status mapping
  • Error mapping
  • Bulk and async jobs
  • Code example
  • Cutover checklist
Javascript