// post /v1/bulk/verifier
API Bulk Email Verifier
Pulisci e valuta elenchi di email ad alto volume con una sola pipeline di verifica asincrona, pensata per chi invia su larga scala.
Email addressesFino a 20,000 righe
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 · richiesta
Email Verifier in blocco è una sola richiesta HTTPS
Invia i parametri con la tua chiave e il tuo secret. Ogni SDK, la CLI e il server MCP fanno questa stessa chiamata.
- type
- verifier
- list | data | file
- Email addresses
- launch
- true avvia subito il job
- webhook_url
- Riceve un evento firmato quando il job termina
- rows
- Fino a 20,000 per job
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 · risposta
Cosa ricevi
JSON, uguale in ogni linguaggio. I campi che Tomba non conosce sono null, mai indovinati.
GET
/email-verifierdata.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
}
}Ogni riga, come la restituisce GET /email-verifier
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 · costi e limiti
Quanto costa una chiamata
Una chiamata viene addebitata solo alla condizione indicata sotto. I limiti di frequenza dipendono dal tuo piano.
// costo
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)
Crea un'operazione bulk caricando un elenco di indirizzi email, poi avviala. L'API verifica tutte le email in modo asincrono con controlli su più livelli. Usa i webhook o il polling per seguire l'avanzamento.
Puoi verificare fino a 20.000 indirizzi email per operazione bulk. Per elenchi più grandi, crea più operazioni bulk.
Ogni email passa per validazione della sintassi, controllo dei record MX, verifica SMTP, rilevamento di indirizzi usa e getta e catch-all e punteggio di deliverability.
Se un indirizzo che Tomba ha restituito come valido va in hard bounce, il credito viene restituito grazie alla garanzia sulla qualità dei dati (risultato del verifier deliverable o punteggio del finder di almeno 60, inviato entro 30 giorni da un dominio con SPF, DKIM e DMARC).
La velocità dipende dalla dimensione della lista e dalla rapidità con cui risponde ogni server di posta. Interroga lo stato del job o imposta un webhook per sapere quando termina.
Ogni risultato include l'email, lo stato di verifica (valid, invalid, accept_all, unknown), il punteggio di affidabilità, l'indicatore usa e getta, il provider SMTP e i record MX.
Al termine dell'elaborazione, usa l'endpoint di download per ottenere i risultati in CSV o JSON. I risultati includono tutti i dati di verifica di ogni email.
Sì, configura un URL webhook per ricevere notifiche quando la verifica in blocco è completata o quando si verificano errori durante l'elaborazione.
I domini accept-all possono essere validi ma più rischiosi. Dai priorità ai punteggi di affidabilità più alti e valuta strategie di invio segmentate per questi record.
Verifica gli elenchi a ridosso dell'invio, escludi gli indirizzi non validi e usa e getta, e verifica di nuovo periodicamente gli elenchi più vecchi per mantenere la deliverability.