Copy page

Email finders

Migrate from Findymail

This guide maps the Findymail API (the /api/search/* endpoints, /api/verify, and /api/credits) to Tomba. Findymail API behavior checked on 2026-09-29 against the Findymail 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.
• Findymail endpoints take POST requests with JSON bodies. Tomba lookups are GET requests with query parameters.

Endpoint mapping

Replace the host app.findymail.com with api.tomba.io.

Authentication changes

Findymail reads a bearer token. Tomba needs two headers, X-Tomba-Key and X-Tomba-Secret:

Code
# Findymail
curl -X POST "https://app.findymail.com/api/search/name" \
  -H "Authorization: Bearer $FINDYMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "domain": "stripe.com"}'

# Tomba
curl -G "https://api.tomba.io/v1/email-finder" \
  --data-urlencode "full_name=Jane Doe" \
  --data-urlencode "domain=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

Response field mapping

Tomba wraps every result in data.

The email finder returns its best match with a verification status in data.verification.status, including catch-all (accept_all) and unconfirmed (unknown) matches. If your code expects only verified addresses, keep results whose status is valid.

Status mapping

Findymail's verifier returns a boolean. Tomba returns a detailed status and a result verdict:

Compare status case-insensitively. Each value is defined in Status values.

Error mapping

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

Bulk and async jobs

A Tomba lookup always returns its result in the response. With webhook_url it also posts a copy, but the request doesn't move to the background as it does on Findymail.

Findymail has no bulk endpoint. To process a list with Tomba, replace per-contact loops with a bulk job: finder for names and companies, linkedin for profile URLs, enrich for email addresses, search for domains, and verifier for verification. Email finder jobs take a CSV file:

Code
curl -X POST "https://api.tomba.io/v1/bulk/finder" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
  -F "name=Conference leads" \
  -F "file=@leads.csv;type=text/csv" \
  -F "full_name_field_index=0" \
  -F "domain_field_index=1"

Tomba treats the first row of the file as a header. Launch the job, poll its progress, and download the results as shown in Lifecycle. Input formats per type are in Bulk types, and a job is charged when you first download its results; see Billing.

Code example

This function replaces a call to POST /api/search/name and returns Findymail's contact shape, or null when no address is found. 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,
};

// Findymail's `domain` field accepts a domain or a company name.
// Tomba takes a domain as `domain` and a company name as `company`.
async function findFromName(name, domainOrCompany) {
    const url = new URL("https://api.tomba.io/v1/email-finder");
    url.searchParams.set("full_name", name);
    url.searchParams.set(
        domainOrCompany.includes(".") ? "domain" : "company",
        domainOrCompany,
    );

    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 { email, full_name, website_url, verification } = body.data;
    if (!email) return null;
    return {
        contact: { name: full_name, domain: website_url, email },
        status: verification?.status ?? null,
    };
}

console.log(await findFromName("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 a bearer token.
2. Change each POST with a JSON body into a GET with query parameters, and send Findymail's domain value as domain or company.
3. Read results from data instead of contact, treat data.email: null as no match, and filter on data.verification.status if you need verified addresses only.
4. Handle 402 as before, retry 429 after Retry-After, skip 400 unknown_record domains, and remove addresses that return 451.
5. Move large lists from per-contact loops to bulk jobs, and set webhook_url or poll /progress to know when they end.
6. Run the same sample of contacts through both services and compare the results before you switch production traffic.