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 Clearout

This guide maps the Clearout API v2 email verification endpoints (instant verify, bulk verify, and available credits) to the Tomba Email Verifier and bulk verifier jobs. Clearout API behavior checked on 2026-09-30 against the Clearout 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

Replace the base URL https://api.clearout.io/v2 with https://api.tomba.io/v1. Clearout shows the base URL for your account's region under Developer, Reference in its app; replace that one if it differs.

ClearoutTomba
POST /email_verify/instantGET /v1/email-verifier
POST /email_verify/bulkPOST /v1/bulk/verifier, then PUT /v1/bulk/verifier/{id} to launch
GET /email_verify/bulk/progress_statusGET /v1/bulk/verifier/{id}/progress
POST /download/resultGET /v1/bulk/verifier/{id}/download
POST /email_verify/list/removeDELETE /v1/bulk/verifier/{id}/delete
POST /email_verify/list/cancelNo equivalent
POST /email_verify/listGET /v1/bulk/verifier
GET /email_verify/getcreditsGET /v1/me

Clearout's single-check endpoints (/email/verify/catchall, /disposable, /business, /free, /role, /gibberish) have no separate Tomba endpoints. The Email Verifier response carries accept_all, disposable, webmail, and gibberish for every address.

Authentication changes

Clearout reads an API token from the Authorization header. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

TerminalCode
# Clearout curl -X POST "https://api.clearout.io/v2/email_verify/instant" \ -H "Authorization: Bearer $CLEAROUT_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"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 takes the address as a query parameter on a GET request, not in a JSON body. Tomba API keys expire; plan their rotation with Key expiry.

Parameter mapping

ClearoutTombaNotes
Authorization headerX-Tomba-Key and X-Tomba-Secret headers
emailemailRequired. A malformed address returns 422 params_invalid instead of a result.
timeoutNo equivalentSet the timeout in your HTTP client.
response=flatNo equivalentRead the checks from data.email.
Bulk filefileCSV only, sent with the content type text/csv. Convert XLSX files first. Also send name.
Email column found by its headeremail_field_indexZero-based, and optional when the header names the column, such as email.
Bulk optimizeNo equivalent
Bulk ignore_duplicate_fileNo equivalent
list_id{id} in the path

Response field mapping

Clearout returns the result in data. 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.

ClearoutTombaNotes
status (top level)HTTP status codeSee Error mapping.
data.email_addressdata.email.emailAn empty string when the domain is disposable.
data.statusdata.email.status, data.email.resultSee Status mapping.
data.safe_to_senddata.email.resultThe closest field; see Result values.
data.sub_status.code, data.sub_status.descNo equivalentTomba reports greylisted, block, and mx_check as separate fields.
data.disposabledata.email.disposableA boolean instead of "yes" or "no".
data.freedata.email.webmailA boolean instead of "yes" or "no".
data.gibberishdata.email.gibberishA boolean instead of "yes" or "no".
data.roleNo equivalent
data.detail_info.mx_recorddata.email.mx.recordsAn array of MX host names instead of one string.
data.detail_info.smtp_providerdata.email.smtp_provider
data.detail_info.account, .domainNo equivalentSplit the address at @.
data.suggested_email_addressNo equivalent
data.bounce_typeNo equivalent
data.verified_on, data.time_takenNo equivalent
data.profileNo equivalent
error.code, error.messageerrors.type, errors.messageSee Error mapping.

Tomba also returns score, accept_all, block, greylisted, regex, and whois, which have no field in Clearout's instant verify response. Read your remaining balance from the X-Verify-Remaining header or GET /v1/me; see Check usage.

Status mapping

Clearout documents four primary statuses. Its API returns them in data.status; the example response shows valid in lower case, so compare case-insensitively.

Clearout statusTomba statusTomba result
Validvaliddeliverable
Invalidinvalidundeliverable
Invalid, sub-status 400 (syntax error)No status. The request fails with 422 params_invalid.
Catch Allaccept_allrisky
Unknownunknownrisky
Any status with disposable: "yes"disposableEmpty string

Tomba reports a disposable domain as its own status rather than as a flag next to a mailbox result. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Both APIs signal failures with HTTP status codes. Clearout's error body is {"status": …, "error": {"code", "message"}}; Tomba's is an errors object with type, message, and code.

ClearoutTombaWhat to do
400 Bad Request422 params_invalidFix the parameter named in the message.
401 Unauthorized400 authentication_failed (missing or malformed), 400 api_key_expired, 401 authentication_failed (wrong key or secret)Check both headers; rotate an expired key.
402 with code 1002, 1028, or 1031402 quota_exceeded on single requestsFor bulk jobs, the balance is checked at the first download instead; see Billing.
429 with code 1030429 rate_limitRetry after the Retry-After delay, not x-ratelimit-reset; see Handle 429 responses.
Code 1001 (too many bulk requests)429 rate_limit (running job limit)Wait for a running job to finish; see Limits.
Code 1004 (no email column found)422 params_invalidName the header email, or send email_field_index.
415 Invalid Content TypeNo equivalentTomba's single check is a GET request with no body.
500, 503500 api_errorRetry with backoff.
524 Request TimeoutNo equivalentTomba returns the final result; keep the client timeout at 180 seconds or more.
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

ClearoutTomba
POST /email_verify/bulk with a CSV or XLSX filePOST /v1/bulk/verifier with name and a CSV file, or a newline-separated list of addresses
Verification is queued on uploadLaunch the job: PUT /v1/bulk/verifier/{id}
Poll progress_status for progress_status and percentilePoll GET /v1/bulk/verifier/{id}/progress for status and progress until status is completed
The email_verifier.bulk.completed webhookwebhook_url, which receives a signed bulk.completed event. See Bulk job events.
POST /download/result returns a file URL in data.urlGET /v1/bulk/verifier/{id}/download?file=full returns the CSV itself
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"

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 /email_verify/instant and returns Clearout'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 -> Clearout primary status, as Clearout's docs name them. // Its API example returns "valid" in lower case; compare case-insensitively. const STATUSES = { valid: "Valid", invalid: "Invalid", accept_all: "Catch All", unknown: "Unknown", }; const yesNo = (value) => (value ? "yes" : "no"); async function instantVerify(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; const status = check.status.toLowerCase(); return { email_address: check.email || email, // A disposable address has no mailbox status in Tomba. status: STATUSES[status] ?? "Unknown", disposable: yesNo(status === "disposable" || check.disposable), free: yesNo(check.webmail), gibberish: yesNo(check.gibberish), detail_info: { mx_record: check.mx?.records?.[0] ?? null, smtp_provider: check.smtp_provider, }, }; } console.log(await instantVerify("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 the Authorization header.
  2. Change instant verification from a POST with a JSON body to GET https://api.tomba.io/v1/email-verifier?email=, drop timeout, and set a client timeout of at least 180 seconds.
  3. Swap error handling: 422 for bad parameters, 402 for credits, 429 with Retry-After, and 408 and 451 as new cases.
  4. Translate status with the status mapping, comparing it case-insensitively, and read disposable, webmail, and gibberish as booleans.
  5. Replace bulk uploads with verifier bulk jobs: convert XLSX to CSV, launch, receive the webhook_url event instead of the webhook, 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
EmailableDeBounce
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