How does the Bulk Email Verifier API work?

Create a bulk operation by uploading a list of email addresses, then launch the operation. The API verifies all emails asynchronously using multi-layer checks. Use webhooks or polling to monitor progress.

What is the maximum batch size?

You can verify up to 20,000 email addresses per bulk operation. For larger lists, create multiple bulk operations.

What verification checks are performed?

Each email undergoes syntax validation, MX record checks, SMTP verification, disposable detection, catch-all detection, and deliverability scoring.

What is the data-quality guarantee?

If an address Tomba returned as valid hard-bounces, the credit comes back under the data-quality guarantee (verifier result deliverable or finder score of 60 or more, sent within 30 days from a domain with SPF, DKIM and DMARC).

How long does verification take?

A velocidade depende do tamanho da lista e da rapidez com que cada servidor de email responde. Consulte o status da tarefa ou configure um webhook para saber quando ela terminar.

What results are returned?

Each result includes the email, verification status (valid, invalid, accept_all, unknown), confidence score, disposable flag, SMTP provider, and MX records.

How do I download results?

Once processing completes, use the download endpoint to get results as CSV or JSON. Results include all verification data for each email.

Are webhooks supported?

Yes, configure a webhook URL to receive notifications when your bulk verification completes or when errors occur during processing.

How should I treat accept-all results?

Accept-all domains can be valid but riskier. Prioritize higher confidence scores and consider segmented sending strategies for these records.

What is a recommended verification workflow?

Verify lists close to send time, suppress invalid and disposable addresses, and re-verify older lists periodically to maintain deliverability.

// post /v1/bulk/verifier

Bulk Email Verifier API

Clean and score high-volume email lists with one asynchronous verification pipeline built for senders at scale.

Obter chave de API grátis Referência da API

Email addressesAté 20,000 linhas

POST /bulk/verifier

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":"Email Verifier job","list":"richard@piedpiper.com\njohn@example.com","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'

const res = await fetch("https://api.tomba.io/v1/bulk/verifier", {
  method: "POST",
  headers: {
    "X-Tomba-Key": process.env.TOMBA_API_KEY,
    "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "Email Verifier job",
    "list": "richard@piedpiper.com\njohn@example.com",
    "launch": true,
    "webhook_url": "https://hooks.example.com/tomba"
  })
});
const { data } = await res.json(); // { id }

import os, requests

res = requests.post(
    "https://api.tomba.io/v1/bulk/verifier",
    headers={
        "X-Tomba-Key": os.environ["TOMBA_API_KEY"],
        "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
    },
    json={
      "name": "Email Verifier job",
      "list": "richard@piedpiper.com\njohn@example.com",
      "launch": True,
      "webhook_url": "https://hooks.example.com/tomba"
    },
)
job_id = res.json()["data"]["id"]

// 01 · requisição

Massa Email Verifier é uma requisição HTTPS

Envie os parâmetros com sua chave e seu secret. Todos os SDKs, a CLI e o servidor MCP fazem esta mesma chamada.

type: verifier
list | data | file: Email addresses
launch: true inicia o job imediatamente
webhook_url: Recebe um evento assinado quando o job termina
rows: Até 20,000 por job

POST /bulk/verifier

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":"Email Verifier job","list":"richard@piedpiper.com\njohn@example.com","launch":true,"webhook_url":"https://hooks.example.com/tomba"}'

const res = await fetch("https://api.tomba.io/v1/bulk/verifier", {
  method: "POST",
  headers: {
    "X-Tomba-Key": process.env.TOMBA_API_KEY,
    "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "Email Verifier job",
    "list": "richard@piedpiper.com\njohn@example.com",
    "launch": true,
    "webhook_url": "https://hooks.example.com/tomba"
  })
});
const { data } = await res.json(); // { id }

import os, requests

res = requests.post(
    "https://api.tomba.io/v1/bulk/verifier",
    headers={
        "X-Tomba-Key": os.environ["TOMBA_API_KEY"],
        "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
    },
    json={
      "name": "Email Verifier job",
      "list": "richard@piedpiper.com\njohn@example.com",
      "launch": True,
      "webhook_url": "https://hooks.example.com/tomba"
    },
)
job_id = res.json()["data"]["id"]

// 02 · resposta

O que volta

JSON, igual em todas as linguagens. Campos que a Tomba não conhece vêm como null, nunca adivinhados.

GET/email-verifierCampo

data.email.resultstring: deliverable, risky or undeliverable; empty for a disposable domain
data.email.statusstring: valid, accept_all, invalid, unknown or disposable (compare case-insensitively: a live check can return Valid)
data.email.scoreinteger: Confidence: 99 for valid, 77 or more for accept_all, 2 for disposable
data.email.smtp_providerstring | null: Mail provider from the MX records, such as Google
data.email.mx.recordsarray | null: The domain's MX hosts
data.email.mx_check, data.email.smtp_checkboolean: The domain has MX records (smtp_check is the same check; status says whether the mailbox exists)
data.email.accept_all, data.email.greylisted, data.email.blockboolean: Catch-all domain, check deferred, check refused by the server
data.email.disposable, data.email.webmail, data.email.gibberish, data.email.regexboolean: Disposable or webmail domain, random-looking address, valid syntax
data.sources[]array: Where the address was found
data.phone_data[]array | null: Phone numbers, when you send enrich_mobile

POST /bulk/verifier

201 Created

{
  "data": {
    "id": 1042
  }
}

Cada linha, como GET /email-verifier a retorna

200 OK

{
  "data": {
    "email": {
      "email": "richard@piedpiper.com",
      "result": "deliverable",
      "status": "valid",
      "score": 99,
      "smtp_provider": "Google",
      "mx": {
        "records": [
          "aspmx.l.google.com",
          "alt1.aspmx.l.google.com"
        ]
      },
      "mx_check": true,
      "smtp_server": true,
      "smtp_check": true,
      "accept_all": false,
      "greylisted": false,
      "block": false,
      "gibberish": false,
      "disposable": false,
      "webmail": false,
      "regex": true,
      "whois": {
        "registrar_name": null,
        "referral_url": null,
        "created_date": null
      }
    },
    "sources": [
      {
        "uri": "https://piedpiper.com/blog/engineering",
        "website_url": "piedpiper.com",
        "extracted_on": "2024-06-01T09:14:07+01:00",
        "last_seen_on": "2025-01-10T17:02:44+01:00",
        "still_on_page": true
      }
    ],
    "phone_data": null
  }
}

// 03 · custo e limites

Quanto custa uma chamada

Uma chamada só é cobrada na condição abaixo. Os limites de requisições dependem do seu plano.

// custo

1 verification credit per row, except disposable addresses. Plus 5 search credits per row with phone data.

Charged once, at the first download; later downloads are free

Jobs created: 15 per day for each type
Running jobs: 2 per type
Downloads: 25 per day for each job
Request size: 4 MB (CSV, list or rows)

// faq

Frequently Asked Questions

Ainda tem dúvidas? Visite a central de ajuda

Faça sua primeira chamada em um minuto

Conta gratuita, chave de API real, os mesmos endpoints que os clientes Enterprise usam.

1Crie uma conta gratuita25 buscas por mês. Sem cartão.

2Copie sua chave e seu secretEm Chaves de API, no painel.

3Chame a APICole a requisição; a resposta vem em JSON.

const res = await fetch("https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks", { headers: { "X-Tomba-Key": process.env.TOMBA_API_KEY, "X-Tomba-Secret": process.env.TOMBA_SECRET_KEY } }); const { data } = await res.json();

import os, requests res = requests.get( "https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks", headers={ "X-Tomba-Key": os.environ["TOMBA_API_KEY"], "X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"], }, ) data = res.json()["data"]

{ "data": { "email": "richard@piedpiper.com", "first_name": "Richard", "last_name": "Hendricks", "full_name": "Richard Hendricks", "website_url": "piedpiper.com", "company": "Pied Piper", "pattern": "{first}", "department": "executive", "type": "personal", "position": "CEO", "country": "US", "gender": "male", "twitter": null, "linkedin": "https://www.linkedin.com/in/richard-hendricks", "score": 100, "accept_all": false, "phone_number": true, "verification": { "date": "2025-01-15T10:32:00+01:00", "status": "valid" }, "sources": [ { "uri": "https://piedpiper.com/blog/engineering", "website_url": "piedpiper.com", "extracted_on": "2024-06-01T09:14:07+01:00", "last_seen_on": "2025-01-10T17:02:44+01:00", "still_on_page": true } ], "phone_data": [] } }

Bulk Email Verifier API

Massa Email Verifier é uma requisição HTTPS

O que volta

Quanto custa uma chamada

Endpoints relacionados

Frequently Asked Questions

Faça sua primeira chamada em um minuto