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 NeverBounce

This guide maps the NeverBounce API v4.2 (single check, jobs, and account info) to the Tomba Email Verifier and bulk verifier jobs. NeverBounce API behavior checked on 2026-09-29 against the NeverBounce 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. A client timeout of about 10 seconds, as NeverBounce suggests, cuts off Tomba verifications that take longer.

Endpoint mapping

Replace the base URL https://api.neverbounce.com/v4.2 (or /v4) with https://api.tomba.io.

NeverBounceTomba
GET /single/check (or POST)GET /v1/email-verifier
POST /jobs/createPOST /v1/bulk/verifier
POST /jobs/parseNot needed. Tomba parses the list when you create the job.
POST /jobs/startPUT /v1/bulk/verifier/{id}
GET /jobs/statusGET /v1/bulk/verifier/{id}/progress
GET /jobs/resultsNo equivalent. Download the job's CSV.
GET /jobs/downloadGET /v1/bulk/verifier/{id}/download
POST /jobs/deleteDELETE /v1/bulk/verifier/{id}/delete
GET /jobs/searchGET /v1/bulk/verifier
GET /account/infoGET /v1/me

Authentication changes

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

TerminalCode
# NeverBounce curl "https://api.neverbounce.com/v4.2/single/check?key=$NEVERBOUNCE_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

NeverBounceTombaNotes
emailemailRequired. A malformed address returns 422 params_invalid instead of a result.
timeoutNo equivalentSet the timeout in your HTTP client.
address_infoNo equivalent
credits_infoNo equivalentRead the X-Verify-Remaining header or GET /v1/me; see Check usage.

Response field mapping

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

NeverBounceTombaNotes
statusHTTP status code, errors.typeSee Error mapping.
resultdata.email.status, data.email.resultSee Status mapping.
flagsBooleans in data.emailSee the flag table below.
suggested_correctionNo equivalent
execution_timeNo equivalent
address_infoNo equivalentdata.email.email holds the address that was checked.
credits_infoX-Verify-Remaining header, GET /v1/meSee Check usage.
NeverBounce flagTomba field
has_dns_mxdata.email.mx_check is true
free_email_hostdata.email.webmail is true
disposable_emaildata.email.disposable is true
accepts_alldata.email.accept_all is true
bad_syntaxThe request fails with 422 params_invalid
has_dns, bad_dns, temporary_dns_error, smtp_connectable, connect_fails, role_account, profanity, government_host, academic_host, military_host, international_host, squatter_host, spamtrap_network, spelling_mistake, contains_alias, contains_subdomain, historical_responseNo equivalent

Tomba also returns block, greylisted, gibberish, regex, smtp_provider, mx.records, and whois, which have no NeverBounce counterpart.

Status mapping

NeverBounce resultTomba statusTomba result
validvaliddeliverable
invalidinvalidundeliverable
disposabledisposableEmpty string
catchallaccept_allrisky
unknownunknownrisky

Branch on status: it has one value for each NeverBounce result, while result groups accept_all and unknown as risky. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

NeverBounce reports failures in the status field of an HTTP 200 response. Tomba returns an HTTP error status with an errors object, so check the status code rather than a field in the body.

NeverBounce statusTombaWhat to do
auth_failure400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
throttle_triggered429 rate_limitRetry after the Retry-After delay; see Handle 429 responses.
temp_unavail500 api_error, 504, or 408 proxy_errorRetry with backoff. 408 means the mailbox check failed.
general_failure422 params_invalid for a bad parameter, 402 quota_exceeded when your credits don't cover the requestRead errors.type to find the cause.
bad_referrerNo equivalent
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

NeverBounceTomba
jobs/create with input_location: supplied and inputPOST /v1/bulk/verifier with name and a newline-separated list of addresses
jobs/create with input_location: remote_urlNo equivalent. Upload the file as file; set email_field_index (zero-based) if its header doesn't name the address column.
auto_parse, jobs/parseNot needed
auto_start, jobs/startLaunch with PUT /v1/bulk/verifier/{id}
run_sampleNo equivalent
callback_urlwebhook_url, which receives a signed bulk.completed event. See Bulk job events.
jobs/download segmentation (valids, invalids, …)GET /v1/bulk/verifier/{id}/download with file=full or file=valid
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 single/check and returns NeverBounce's result value and the flags Tomba can supply. 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 -> NeverBounce result const RESULTS = { valid: "valid", invalid: "invalid", disposable: "disposable", accept_all: "catchall", unknown: "unknown", }; async function singleCheck(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) { // Failures use HTTP status codes, for example 402, 429, or 451. throw new Error( `${res.status} ${body.errors.type}: ${body.errors.message}`, ); } const check = body.data.email; const flags = []; if (check.mx_check) flags.push("has_dns_mx"); if (check.webmail) flags.push("free_email_host"); if (check.disposable) flags.push("disposable_email"); if (check.accept_all) flags.push("accepts_all"); return { result: RESULTS[check.status.toLowerCase()] ?? "unknown", flags }; } console.log(await singleCheck("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 key parameter from your URLs and logs.
  2. Point single checks at GET https://api.tomba.io/v1/email-verifier and raise your client timeout to at least 180 seconds.
  3. Replace checks of the status field with HTTP status handling: 402, 429 with Retry-After, 451, and 408.
  4. Translate result and flags with the status mapping and flag table, comparing status case-insensitively.
  5. Replace jobs with verifier bulk jobs: create with list or file, launch, receive the webhook_url event instead of the 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 October 7, 2026
OverviewMillionVerifier
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