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 Kickbox

This guide maps the Kickbox API v2 (single verification, batch verification, and balance) to the Tomba Email Verifier and bulk verifier jobs. Kickbox API behavior checked on 2026-09-29 against Kickbox's official client libraries on GitHub.

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

KickboxTomba
GET /v2/verifyGET /v1/email-verifier
PUT /v2/verify-batchPOST /v1/bulk/verifier, then PUT /v1/bulk/verifier/{id} to launch
GET /v2/verify-batch/{id}GET /v1/bulk/verifier/{id}/progress, then GET /v1/bulk/verifier/{id}/download
GET /v2/balanceGET /v1/me

Authentication changes

Kickbox's client libraries send the key as Authorization: token <key>. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

TerminalCode
# Kickbox curl "https://api.kickbox.com/v2/verify?email=jane.doe@stripe.com" \ -H "Authorization: token $KICKBOX_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

KickboxTombaNotes
emailemailRequired. A malformed address returns 422 params_invalid instead of a result.
timeoutNo equivalentKickbox's value is in milliseconds. Set the timeout in your HTTP client instead.

Response field mapping

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

KickboxTombaNotes
resultdata.email.result, data.email.statusSee Status mapping.
reasondata.email.status and the booleans in data.emailSee Status mapping.
roleNo equivalent
freedata.email.webmail
disposabledata.email.disposable
accept_alldata.email.accept_all
did_you_meanNo equivalent
sendexdata.email.scoreKickbox scores from 0 to 1; Tomba's integer score is computed differently. Recalibrate any threshold you apply to it.
emaildata.email.emailAn empty string when the domain is disposable.
user, domainNo equivalentSplit data.email.email at @.
success, messageHTTP status code, errors.messageSee Error mapping.
X-Kickbox-Balance headerX-Verify-Remaining headerTomba's value is the balance before the current request; see Check usage.
X-Kickbox-Response-Time headerNo equivalent

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

Status mapping

Kickbox resultTomba statusTomba result
deliverablevaliddeliverable
undeliverableinvalidundeliverable
riskyaccept_allrisky
risky, with disposable: truedisposableEmpty string
unknownunknownrisky
Kickbox 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 when the domain accepts all mail
low_qualityNo single equivalent. Check disposable, webmail, and gibberish.
no_connect, timeout, invalid_smtp, unavailable_smtp, unexpected_errorNo 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

Both APIs signal failures with HTTP status codes. Tomba's error body is an errors object with type, message, and code.

KickboxTombaWhat to do
403 Insufficient balance402 quota_exceededWait for your usage window to renew or add credits.
Other 4xx with a message400 or 401 authentication_failed for credentials, 400 api_key_expired, 422 params_invalid for parametersRead errors.type to find the cause; rotate an expired key.
5xx500 api_errorRetry with backoff.

Tomba also returns 429 rate_limit when you exceed your plan's rate limits (retry after Retry-After; see Handle 429 responses), 408 proxy_error when the mailbox check fails, and 451 claimed_email when the owner of the address asked Tomba to stop processing it. Remove 451 addresses from your list. Error responses don't consume credits; every type is listed in Errors.

Bulk and async jobs

KickboxTomba
PUT /v2/verify-batch with newline-separated addresses and an X-Kickbox-Filename headerPOST /v1/bulk/verifier with a name and a newline-separated list, or a CSV file
The batch starts on submissionLaunch it: PUT /v1/bulk/verifier/{id}
GET /v2/verify-batch/{id}Poll GET /v1/bulk/verifier/{id}/progress until status is completed, then download the CSV from GET /v1/bulk/verifier/{id}/download. Or set webhook_url to receive an event when the job ends.
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 /v2/verify and returns Kickbox's field names for the values Tomba provides. 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 -> Kickbox result const RESULTS = { valid: "deliverable", invalid: "undeliverable", accept_all: "risky", disposable: "risky", unknown: "unknown", }; 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 { result: RESULTS[check.status.toLowerCase()] ?? "unknown", email: check.email || email, free: check.webmail, disposable: check.disposable, accept_all: check.accept_all, success: true, }; } 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.
  2. Point single verifications at GET https://api.tomba.io/v1/email-verifier, drop the timeout parameter, and set a client timeout of at least 180 seconds.
  3. Read results from data.email and translate result and reason with the status mapping, comparing status case-insensitively.
  4. Handle 402 where you handled 403 Insufficient balance, retry 429 after Retry-After, and drop addresses that return 451.
  5. Replace batches with verifier bulk jobs: create, launch, poll /progress, 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
BouncerHunter
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