Copy page

Email finders

Migrate from Snov.io

This guide maps the Snov.io API (the v2 email finder, domain search, email verifier, LinkedIn profile, and company domain methods, and the v1 email count, profile, and balance methods) to Tomba. Snov.io API behavior checked on 2026-09-29 against the Snov.io API reference.

Before you begin

• Get your API key (ta_…) and secret (ts_…); see Authentication.
• Check what each endpoint costs in Credit costs and your plan's throttling in Limits by plan.
• Snov.io's v2 methods are asynchronous: you start a task, then fetch its result with the task_hash. Tomba returns the result in the response, so each start and result pair becomes one request. Set your HTTP client timeout to at least 180 seconds.

Endpoint mapping

Replace the host api.snov.io with api.tomba.io.

Authentication changes

Snov.io exchanges a client ID and secret for an access token that lasts one hour, then sends it as a bearer token. Tomba has no token exchange: send the key and secret as X-Tomba-Key and X-Tomba-Secret on every request.

Code
# Snov.io: get an access token
curl -X POST "https://api.snov.io/v1/oauth/access_token" \
  -d "grant_type=client_credentials" \
  -d "client_id=$SNOV_CLIENT_ID" \
  -d "client_secret=$SNOV_CLIENT_SECRET"

# Tomba: send the key and secret with the request
curl "https://api.tomba.io/v1/email-finder?domain=stripe.com&first_name=Jane&last_name=Doe" \
  -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

Response field mapping

Tomba wraps every result in data.

Status mapping

The email finder uses the same status values in data.verification.status, which is null when the address hasn't been verified. Compare status case-insensitively. Each value is defined in Status values.

Error mapping

Snov.io reports a lack of credits in the result's status field. Tomba returns an HTTP error status with an errors object:

Also handle Tomba's 400 and 401 authentication_failed for missing or wrong credentials, 422 params_invalid for bad parameters, 429 rate_limit when you exceed your plan's rate limits (see Handle 429 responses), and 451 claimed_email when the owner of an address asked Tomba to stop processing it. Error responses don't consume credits; every type is listed in Errors.

Bulk and async jobs

Replace each Snov.io start and result pair with a single Tomba request, and remove the code that stores task_hash values and polls for results. For lists, run a Tomba bulk job instead of sending batches of 10:

Each job is created, launched, polled, and downloaded as CSV; see Lifecycle. To be notified when a job ends, set webhook_url; see Bulk job events. A job is charged when you first download its results; see Billing.

Code example

This function replaces the emails-by-domain-by-name start and result calls. It returns the same shape as Snov.io's result data array. 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,
};

// rows: [{ first_name, last_name, domain }], as sent to Snov.io.
async function emailsByDomainByName(rows) {
    const data = [];
    for (const { first_name, last_name, domain } of rows) {
        const url = new URL("https://api.tomba.io/v1/email-finder");
        url.search = new URLSearchParams({
            first_name,
            last_name,
            domain,
        }).toString();

        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 found = body.data;
        const status = found.verification?.status?.toLowerCase();
        data.push({
            people: `${first_name} ${last_name}`,
            result: found.email
                ? [
                      {
                          email: found.email,
                          smtp_status: status === "valid" ? "valid" : "unknown",
                      },
                  ]
                : [],
        });
    }
    return data;
}

const data = await emailsByDomainByName([
    { first_name: "Jane", last_name: "Doe", domain: "stripe.com" },
    { first_name: "John", last_name: "Smith", domain: "shopify.com" },
]);
console.log(JSON.stringify(data, null, 2));

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 access token exchange and refresh.
2. Replace each start and result pair with one GET request, and delete task_hash storage and polling.
3. Send one person, address, profile, or name per request, and move large lists to bulk jobs.
4. Translate smtp_status and unknown_status_reason with the status mapping, comparing status case-insensitively.
5. Handle 402 where you handled not_enough_credits, retry 429 after Retry-After, and drop addresses that return 451.
6. Run the same sample of people and addresses through both services and compare the results before you switch production traffic.