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

BouncerTomba
GET /v1.1/email/verifyGET /v1/email-verifier
POST /v1.1/email/verify/batchPOST /v1/bulk/verifier, then PUT /v1/bulk/verifier/{id} to launch
GET /v1.1/email/verify/batch/{batchId}GET /v1/bulk/verifier/{id}/progress
GET /v1.1/email/verify/batch/{batchId}/downloadGET /v1/bulk/verifier/{id}/download
POST /v1.1/email/verify/batch/{batchId}/finishNo equivalent
DELETE /v1.1/email/verify/batch/{batchId}DELETE /v1/bulk/verifier/{id}/delete
POST /v1.1/email/verify/batch/syncNo equivalent. Use a bulk job, or send single requests.
GET /v1.1/creditsGET /v1/me

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:

TerminalCode
# 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

BouncerTombaNotes
emailemailRequired. A malformed address returns 422 params_invalid instead of a result.
timeoutNo equivalentSet the timeout in your HTTP client.
Batch body [{"email": …}]listA string with one address per line.
Batch callbackNo equivalentPoll the job's progress.
Batch skip-headerNo equivalentTomba always treats the first row of a CSV file as a header.
Status with-statsNo equivalent
Download download=allfile=full
Download download=deliverablefile=valid
Download download risky, undeliverable, unknownNo equivalentDownload file=full and filter the rows.

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.

BouncerTombaNotes
emaildata.email.emailAn empty string when the domain is disposable.
statusdata.email.result, data.email.statusSee Status mapping.
reasondata.email.status and the booleans in data.emailSee Status mapping.
domain.acceptAlldata.email.accept_all
domain.disposabledata.email.disposable
domain.freedata.email.webmail
domain.nameNo equivalentSplit data.email.email at @.
account.role, account.disabled, account.fullMailboxNo equivalent
dns.type, dns.recorddata.email.mx_check, data.email.mx.records
providerdata.email.smtp_provider
scoredata.email.scoreComputed differently. Recalibrate any threshold you apply to it.
toxic, toxicityNo equivalent
retryAfterNo equivalentdata.email.greylisted is true when the mail server deferred the check.
didYouMeanNo equivalent

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

Status mapping

Bouncer statusTomba statusTomba result
deliverablevaliddeliverable
risky, reason low_deliverabilityaccept_allrisky
risky, reason low_qualitydisposableEmpty string
undeliverableinvalidundeliverable
unknownunknownrisky
Bouncer reasonTomba
accepted_emailstatus is valid
rejected_emailstatus is invalid
invalid_emailThe request fails with 422 params_invalid
invalid_domainmx_check is false
low_deliverabilitystatus is accept_all for a catch-all domain. A full mailbox has no equivalent.
low_qualitystatus is disposable for a disposable domain
dns_error, unavailable_smtp, unsupported, timeout, unknownNo equivalent reason. An inconclusive check returns status unknown; a failed check returns 408 proxy_error.

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

BouncerTombaWhat to do
400422 params_invalidFix the parameter named in the message.
401 user not found400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
402 Payment Required402 quota_exceededWait for your usage window to renew or add credits.
429429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
503500 api_error or 504Retry with backoff.
404 batch not found404 unknown_recordCheck the job ID.
405 batch not completed404Download only after /progress reports completed.
No equivalent408 proxy_errorThe mailbox check failed. Retry later.
No equivalent451 claimed_emailThe owner of the address asked Tomba to stop processing it. Remove it from your list.

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

BouncerTomba
POST /v1.1/email/verify/batch with a JSON array or a text filePOST /v1/bulk/verifier with name and a newline-separated list, or a CSV file
The batch is queued on creationLaunch it: PUT /v1/bulk/verifier/{id}
Poll the batch status, or pass callbackPoll GET /v1/bulk/verifier/{id}/progress until status is completed, or pass webhook_url to receive an event.
Download JSON, or CSV with Accept: text/csvGET /v1/bulk/verifier/{id}/download returns CSV only
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 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.
Last modified on September 30, 2026
BounceBanKickbox
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