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 ZeroBounce

This guide maps the ZeroBounce API v2 (single validation, batch validation, the bulk file API, and credit balance) to the Tomba Email Verifier and bulk verifier jobs. ZeroBounce API behavior checked on 2026-09-30 against the ZeroBounce 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.

Endpoint mapping

ZeroBounce uses the hosts api.zerobounce.net (or api-us, api-eu) and bulkapi.zerobounce.net. Tomba serves everything from api.tomba.io.

ZeroBounceTomba
GET /v2/validate (or POST)GET /v1/email-verifier
POST /v2/validatebatchPOST /v1/bulk/verifier, then PUT /v1/bulk/verifier/{id} to launch
POST https://bulkapi.zerobounce.net/v2/sendfilePOST /v1/bulk/verifier, then PUT /v1/bulk/verifier/{id} to launch
GET /v2/filestatusGET /v1/bulk/verifier/{id}/progress
GET /v2/getfileGET /v1/bulk/verifier/{id}/download
GET /v2/deletefileDELETE /v1/bulk/verifier/{id}/delete
GET /v2/getcreditsGET /v1/me

Authentication changes

ZeroBounce reads the key from the api_key parameter, in the query string or the request body. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret, and doesn't accept credentials in the query string or body:

TerminalCode
# ZeroBounce curl "https://api.zerobounce.net/v2/validate?api_key=$ZEROBOUNCE_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"

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

Parameter mapping

ZeroBounceTombaNotes
api_keyX-Tomba-Key and X-Tomba-Secret headers
emailemailRequired. A malformed address returns 422 params_invalid instead of a result.
ip_addressNo equivalent
timeoutNo equivalentSet the timeout in your HTTP client.
activity_data, verify_plusNo equivalent
Batch email_batch[].email_addresslistA newline-separated string of addresses.
Send file filefileMust be sent with the content type text/csv. Also send name.
email_address_columnemail_field_indexZero-based in Tomba: subtract 1.
has_header_rowNo equivalentTomba always reads the first row as a header.
return_urlwebhook_urlReceives a signed event when the job ends. See Bulk job events.
first_name_column, last_name_column, gender_columnNo equivalent
ip_address_column, remove_duplicate, allow_phase_2No equivalent
file_id{id} in the path
Get file download_type, activity_dataNo equivalentTomba's download type selects full or valid rows; see Lifecycle.

Response field mapping

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

ZeroBounceTombaNotes
addressdata.email.emailAn empty string when the domain is disposable.
statusdata.email.status, data.email.resultSee Status mapping.
sub_statusNo equivalentTomba reports greylisted, block, disposable, and mx_check as fields.
free_emaildata.email.webmail
catchall_domaindata.email.accept_all
mx_founddata.email.mx_check
mx_recorddata.email.mx.recordsAn array of MX host names instead of one string.
smtp_providerdata.email.smtp_provider
domain_age_daysNo equivalentdata.email.whois.created_date gives the domain's registration date.
account, domainNo equivalentSplit the address at @.
did_you_meanNo equivalent
active_in_days, active_first_seenNo equivalent
firstname, lastname, genderNo equivalent
city, region, zipcode, countryNo equivalent
processed_atNo equivalent
errorerrors.messageReturned with an HTTP error status; see Error mapping.

Tomba also returns score, block, greylisted, gibberish, regex, and whois, which have no ZeroBounce counterpart. Read your remaining balance from the X-Verify-Remaining header or GET /v1/me; see Check usage.

Status mapping

ZeroBounce statussub_statusTomba statusTomba result
validAnyvaliddeliverable
invalidAnyinvalidundeliverable
invalidfailed_syntax_checkNo status. The request fails with 422 params_invalid.
catch-allAnyaccept_allrisky
unknownAnyunknownrisky
do_not_maildisposabledisposableEmpty string
do_not_mailOther sub-statusesNo equivalent. Tomba returns the mailbox result.
spamtrap, abuseNo equivalent. Tomba returns the mailbox result.

ZeroBounce returns some catch-all domains as valid with the accept_all sub-status. Tomba sets status to accept_all whenever the domain's mail server accepts mail for any address. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

ZeroBounce reports failures in the body: an error string on single validation and credits, an errors array on batch validation, and success: false with error_message on the file endpoints. Tomba returns an HTTP error status with an errors object, so check the status code instead:

ZeroBounceTombaWhat to do
Invalid API Key or your account ran out of credits400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
Invalid API Key or your account ran out of credits402 quota_exceededTomba separates the two cases. Wait for your usage window to renew or add credits.
Temporary block after exceeding the rate limit429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
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.

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

Bulk and async jobs

ZeroBounce's validatebatch returns results in the response. Tomba runs every list as an asynchronous verifier bulk job, so move batch calls to the same flow as your file uploads, or send one GET /v1/email-verifier request per address.

ZeroBounceTomba
validatebatch with email_batchPOST /v1/bulk/verifier with name and a newline-separated list of addresses
sendfile with file and email_address_columnPOST /v1/bulk/verifier with name, a CSV file, and email_field_index
Validation starts on uploadLaunch the job: PUT /v1/bulk/verifier/{id}
Poll filestatus for file_status and complete_percentagePoll GET /v1/bulk/verifier/{id}/progress for status and progress until status is completed
The return_url callbackwebhook_url. See Bulk job events.
getfileGET /v1/bulk/verifier/{id}/download?file=full
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" \ -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, so add one if your ZeroBounce files have none. 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 /v2/validate and returns ZeroBounce's field names for the values Tomba supplies. 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 -> ZeroBounce [status, sub_status] const STATUSES = { valid: ["valid", ""], invalid: ["invalid", ""], accept_all: ["catch-all", ""], unknown: ["unknown", ""], disposable: ["do_not_mail", "disposable"], }; 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) { // Unlike ZeroBounce, errors use HTTP status codes, such as 402 or 429. throw new Error( `${res.status} ${body.errors.type}: ${body.errors.message}`, ); } const check = body.data.email; const [status, sub_status] = STATUSES[check.status.toLowerCase()] ?? STATUSES.unknown; return { address: check.email || email, status, sub_status, free_email: check.webmail, catchall_domain: check.accept_all, mx_found: check.mx_check, mx_record: check.mx?.records?.[0] ?? null, smtp_provider: check.smtp_provider, }; } 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 api_key from your URLs, request bodies, and logs.
  2. Point single validations at GET https://api.tomba.io/v1/email-verifier, drop timeout, and set a client timeout of at least 180 seconds.
  3. Replace checks of the error field with HTTP status handling: 402, 422, 429 with Retry-After, 408, and 451.
  4. Translate status with the status mapping, comparing it case-insensitively, and stop branching on sub_status.
  5. Replace validatebatch and sendfile with verifier bulk jobs: create, launch, receive the webhook_url event instead of return_url, 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
HunterEmailable
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