Riferimento dell'API di verifica e-mail

Autenticazione

POST /v1/email/validate accetta una chiave pubblicabile limitata per origine tramite l'header X-Api-Key — lo stesso tipo di chiave e lo stesso modello di origini consentite di GET /v1/geo. Tutti gli altri endpoint di questa pagina (batch, job di lista, verifica della registrazione) accettano molti indirizzi o un IP arbitrario, quindi richiedono la tua chiave segreta tramite Authorization: Bearer e vanno chiamati solo dal tuo backend; una chiave pubblicabile riceve un 403.

Esempio

curl https://api.watch-ip.com/v1/email/validate \
  -H "X-Api-Key: YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "John.Doe+news@Gmial.com"}'

{
  "email": "John.Doe+news@Gmial.com",
  "domain": "gmial.com",
  "syntaxValid": true,
  "isDisposable": false,
  "normalizedEmail": "john.doe+news@gmial.com",
  "canonicalEmail": "john.doe@gmial.com",
  "disposableSource": null,
  "isFreeProvider": false,
  "isRoleAccount": false,
  "didYouMean": "john.doe+news@gmail.com",
  "mx": {
    "status": "none",
    "host": null
  },
  "verdict": "reject",
  "reasons": [
    "no_mail_server",
    "typo_suspected"
  ]
}

Verdetti e codici motivo

Ogni condizione imposta un verdetto minimo; prevale la più grave, e reasons le elenca tutte, dalla più grave. Se un indirizzo di un provider gratuito sia accettabile lo decidi tu — non modifica mai il verdetto.

Verifica in batch

POST/v1/email/batch

Verifica da 1 a 100 indirizzi in un'unica richiesta con gli stessi controlli e la stessa forma di risultato di POST /v1/email/validate, un risultato per indirizzo nell'ordine di input. Invia { "emails": [...] }. Gli indirizzi dello stesso dominio condividono un'unica ricerca DNS. Conta una richiesta per indirizzo nel limite mensile del tuo piano; un batch che supererebbe il limite viene rifiutato per intero con 429 monthly_limit_exceeded. Per il limite di frequenza al minuto, l'intera chiamata conta come una sola richiesta. Solo chiave segreta.

curl https://api.watch-ip.com/v1/email/batch \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user@gmail.com", "someone@mailinator.com"]}'

{
  "results": [
    { "email": "user@gmail.com", "verdict": "accept", "reasons": [], ... },
    { "email": "someone@mailinator.com", "isDisposable": true, "disposableSource": "list", "verdict": "reject", "reasons": ["disposable_domain"], ... }
  ]
}

Job di lista e-mail

POST/v1/email/jobs

Verifica fino a 100.000 indirizzi in background. Invia JSON { "emails": [...], "filename": "..." } oppure un body text/csv di al massimo 10 MB: viene usata la colonna intitolata email (anche e-mail, email address, email_address o mail, senza distinzione tra maiuscole e minuscole), oppure la prima colonna se nessuna intestazione la indica; i separatori virgola, punto e virgola e tabulazione vengono rilevati. Il job viene addebitato alla creazione — una richiesta per indirizzo distinto (corrispondenza esatta), quindi i duplicati vengono verificati ma addebitati una volta — e una lista che supererebbe il tuo limite mensile viene rifiutata per intero. Se una parte del job non può essere elaborata dopo i tentativi ripetuti, il job viene contrassegnato come failed e i crediti della parte non elaborata vengono restituiti. Risponde 202 con l'oggetto job. Solo chiave segreta; gli stessi job possono essere caricati e scaricati anche dalla pagina Email lists della dashboard.

curl https://api.watch-ip.com/v1/email/jobs \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @newsletter.csv

{
  "id": "5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11",
  "status": "queued",
  "source": "api",
  "filename": null,
  "total": 12840,
  "credits": 12512,
  "processed": 0,
  "summary": null,
  "createdAt": "2026-09-28T10:00:00.000Z",
  "completedAt": null,
  "expiresAt": "2026-10-05T10:00:00.000Z"
}

Stato del job

GET/v1/email/jobs/{id}

Restituisce lo stesso oggetto job. Interrogalo finché status non è completed; le interrogazioni non vengono addebitate.

Risultati del job

GET/v1/email/jobs/{id}/results

Scarica un CSV con una riga per ogni riga inviata, nell'ordine di invio — duplicati inclusi. Colonne: email, normalized_email, verdict, reasons, syntax_valid, is_disposable, disposable_source, is_free_provider, is_role_account, did_you_mean, mx_status, mx_host. reasons è separato da punto e virgola, le celle vuote indicano null e mx_status è vuoto per gli indirizzi sintatticamente non validi (non è stata fatta alcuna ricerca). Un indirizzo non valido che inizia con =, +, - o @ viene preceduto da un apostrofo, così i fogli di calcolo non lo eseguono come formula. 409 finché il job non è completato, 410 una volta scaduto. Il download non viene addebitato.

curl https://api.watch-ip.com/v1/email/jobs/5b0d6f5e-8a51-4f7e-9d0e-2c1f3f7f8a11/results \
  -H "Authorization: Bearer YOUR_SECRET_KEY" -o results.csv

Verifica della registrazione

POST/v1/signup/check

Assegna un punteggio a una registrazione a partire da indirizzo e-mail e IP in un'unica chiamata, dal tuo backend all'invio del modulo di registrazione (un verdetto calcolato nel browser può essere falsificato). Invia { "email": "...", "ip": "...", "userAgent": "..." } — userAgent è facoltativo. La risposta contiene il risultato completo della verifica e-mail (email), il paese e l'ASN dell'IP e — nei piani che includono i dati di sicurezza — i suoi indicatori VPN/Tor/data center/minaccia (ip), l'età del dominio e-mail in giorni secondo i dati pubblici di registrazione (RDAP) (emailDomainAgeDays, null se sconosciuta e per i grandi provider consumer), un punteggio da 0 a 100 (la somma dei pesi dei motivi qui sotto, con un massimo di 100) e un verdetto: reject da 60 in su, review da 25 in su, altrimenti accept. In un piano senza dati di sicurezza, ip.security è null, il punteggio usa solo i segnali dell'e-mail e reasons include ip_security_unavailable. Conta come una richiesta. Solo chiave segreta.

curl https://api.watch-ip.com/v1/signup/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@new-startup.io", "ip": "203.0.113.1"}'

{
  "email": { "email": "jane@new-startup.io", "verdict": "accept", "reasons": [], ... },
  "ip": {
    "ip": "203.0.113.1",
    "country": "US",
    "asn": 64500,
    "asOrganization": "Example Hosting",
    "security": { "isTor": false, "isVpn": false, "isDatacenter": true, "isThreat": false, "isSanctionedNetwork": false }
  },
  "emailDomainAgeDays": 12,
  "score": 45,
  "verdict": "review",
  "reasons": ["new_domain", "ip_datacenter"]
}

Limiti

Ogni indirizzo verificato conta come una richiesta nel limite mensile condiviso del tuo piano — una verifica singola, ogni indirizzo di un batch, ogni indirizzo distinto di un job di lista — e una verifica della registrazione è una richiesta. Batch e job di lista vengono accettati o rifiutati per intero, mai evasi parzialmente. Il limite di frequenza al minuto conta le chiamate HTTP, non gli elementi: un batch fino a 100 IP o indirizzi email conta come una sola richiesta, mentre ogni elemento continua a contare separatamente nel limite mensile di richieste. I caricamenti e i risultati dei job di lista vengono eliminati 7 giorni dopo la creazione del job. Le ricerche DNS hanno un breve budget di tempo: quando una fallisce o va in timeout, il risultato degrada a mx.status unknown e motivo dns_unavailable anziché a un errore. I dati sui domini usa e getta derivano dall'unione di tre liste open source mantenute dalla community, aggiornate ogni poche ore ed estese con i server di posta osservati servire domini in lista — vedi fonti dei dati. Un provider usa e getta molto recente potrebbe non essere ancora segnalato. Tutti i controlli sono a livello di dominio e di indirizzo: nessuna casella di posta viene contattata, quindi nessun risultato stabilisce che una casella esista, chi ne sia il titolare o che la posta vi arriverà.