API di verifica email in tempo reale: guida sviluppatori

La validazione delle email in tempo reale controlla un indirizzo mentre l’utente si trova ancora nel tuo modulo. Viene eseguita nei pochi centinaia di millisecondi tra “Invia” e la schermata successiva e risponde a una domanda: questo indirizzo dovrebbe entrare nel tuo database? Un’API di validazione delle email in tempo reale prende questa decisione per te. Analizza la sintassi, il dominio e i relativi record MX, i segnali relativi agli indirizzi usa e getta e ai ruoli, il comportamento catch-all e, quando lo richiedi, la casella di posta stessa. Poi restituisce un risultato strutturato su cui il tuo codice può agire.

Questa guida è destinata agli sviluppatori che aggiungono questo controllo a un modulo di registrazione, checkout o acquisizione lead. Spiega cosa fanno i controlli, come chiamare un’API, come trasformare ogni stato in una decisione di prodotto e come mantenere la velocità quando un server di posta è lento. Gli esempi usano l’API di validazione delle email di BillionVerify, ma i consigli di progettazione si applicano a qualsiasi provider.

Che cos’è la convalida delle email in tempo reale?

La convalida delle email in tempo reale è un controllo che viene eseguito nel momento in cui viene inserito un indirizzo, non giorni dopo, quando parte una campagna. L’utente inserisce un indirizzo. Il tuo frontend o backend lo invia a un’API di verifica delle email. L’API risponde con uno stato come valid, invalid o catchall, oltre ai segnali alla base del risultato. La tua applicazione consente quindi la registrazione, la blocca o chiede all’utente di correggere un errore di battitura.

Il punto è la tempistica. Un errore come gmial.com non costa nulla da correggere mentre l’utente è ancora nel modulo. Dopo che l’email di benvenuto rimbalza, lo stesso errore ti costa il cliente. Gli indirizzi non validi danneggiano anche la reputazione del mittente, perché ogni rimbalzo permanente comunica ai provider delle caselle che invii email a indirizzi non confermati. La verifica delle email in tempo reale li blocca all’ingresso.

Aiuta anche a contrastare le frodi: un controllo in tempo reale può segnalare una casella usa e getta prima che l’account venga creato.

Convalida delle email in tempo reale vs in blocco

Entrambi gli approcci utilizzano gli stessi controlli. Differiscono nel momento in cui vengono eseguiti e nel tempo a loro disposizione.

• La convalida in tempo reale viene eseguita su un indirizzo alla volta, all’interno di una richiesta dell’utente. Ha un limite di tempo rigido, spesso ben inferiore a un secondo, perché un modulo lento fa perdere iscrizioni. Impedisce l’ingresso di dati errati.
• La convalida in blocco viene eseguita su un’intera lista, in background. Può richiedere minuti o ore e nessuno sta aspettando davanti a una schermata. Pulisce i dati già presenti nel sistema, ad esempio prima di una grande campagna o dopo un’importazione nel CRM.

La maggior parte dei team ha bisogno di entrambi gli approcci. I controlli in tempo reale mantengono puliti i nuovi dati, mentre una verifica periodica in blocco individua gli indirizzi diventati non validi nel tempo, come quelli di dipendenti che hanno lasciato un’azienda. Per un confronto più approfondito, consulta convalida delle email in tempo reale vs in blocco.

Cosa verifica realmente un controllo in tempo reale

Un’API di convalida delle email esegue una serie di controlli, da quelli meno costosi a quelli più costosi. Ognuno esclude un diverso tipo di indirizzo non valido.

Sintassi

Il primo controllo riguarda il formato. C’è esattamente un @? La parte locale contiene solo caratteri consentiti? Il dominio ha l’aspetto di un dominio? La sintassi rifiuta dati evidentemente errati, come john@@example o jane.example.com. È veloce e non richiede alcuna chiamata di rete. Tuttavia, una sintassi perfetta non dice nulla sull’esistenza della casella di posta.

Record del dominio e MX

Successivamente, l’API cerca il dominio in DNS. Un dominio senza record MX non può ricevere email, quindi un indirizzo appartenente a quel dominio è inutile, per quanto corretto possa sembrare. Questo rileva domini digitati erroneamente e domini aziendali non più attivi. BillionVerify restituisce gli host MX trovati in mx_records, mentre domain_suggestion può contenere una probabile correzione quando il dominio sembra un refuso di un dominio comune.

Indicatori di indirizzi usa e getta, di ruolo e di provider gratuiti

Alcuni indirizzi esistono, ma non sono comunque adatti al tuo prodotto:

• Gli indirizzi usa e getta provengono da servizi di posta temporanei e di solito smettono di funzionare entro poche ore. Consulta come funziona il rilevamento delle email usa e getta.
• Gli indirizzi di ruolo, come info@ o support@, appartengono a un team, non a una persona. Di solito sono recapitabili, ma tendono a generare meno coinvolgimento.
• Gli indirizzi di provider gratuiti, come Gmail, sono normali per i consumatori, ma vale la pena registrarli in un modulo B2B.

L’API segnala questi casi tramite flag (is_disposable, is_role, is_free), così puoi decidere in base al prodotto.

Domini catch-all

Alcuni server di posta accettano email per qualsiasi indirizzo del proprio dominio, esistente o meno. Per questi domini catch-all, un controllo della casella non può dimostrare che esista una casella specifica. Un risultato catch-all non è un risultato negativo. Significa che il livello di certezza è inferiore, quindi il punteggio conta più dell’etichetta. Il rilevamento delle email catch-all spiega come funziona e perché è importante.

Controllo della casella tramite SMTP

Il controllo più approfondito chiede al server di posta del destinatario, tramite SMTP, se accetterebbe un messaggio, senza inviarlo. Rileva gli indirizzi appartenenti a domini reali che non esistono più, come la casella di un ex dipendente. È anche il passaggio più lento, perché dipende dal server di qualcun altro. In BillionVerify è controllato dal parametro check_smtp. Se lo ometti, l’API esegue il controllo SMTP; invia check_smtp: false per saltarlo.

Reputazione del dominio

BillionVerify può anche restituire un oggetto domain_reputation con i risultati delle blacklist relative all’IP del server di posta del dominio. Ha solo scopo informativo: non modifica lo stato, il punteggio o il costo.

Come chiamare un'API di convalida email in tempo reale

Con BillionVerify, un singolo controllo in tempo reale consiste in una richiesta HTTPS. L'URL di base è https://api.billionverify.com/v1 e la tua chiave API va inserita nell'header BV-API-KEY. Conserva la chiave sul tuo server. Non inserirla mai nel codice del browser.

Ecco una richiesta minima, basata sul riferimento API:

curl -X POST https://api.billionverify.com/v1/verify/single \
  -H "BV-API-KEY: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","check_smtp":true}'

La richiesta accetta tre parametri:

Una risposta corretta racchiude il risultato in un envelope standard. Ecco un esempio abbreviato per un indirizzo recapitabile:

{
  "success": true,
  "code": "0",
  "message": "Success",
  "data": {
    "email": "user@example.com",
    "status": "valid",
    "score": 0.95,
    "is_deliverable": true,
    "is_disposable": false,
    "is_catchall": false,
    "is_role": false,
    "is_free": false,
    "domain": "example.com",
    "mx_records": ["mail.example.com"],
    "check_smtp": true,
    "reason": "smtp_deliverable",
    "domain_suggestion": "",
    "response_time": 250,
    "credits_used": 1
  }
}

Se preferisci un SDK, BillionVerify pubblica SDK ufficiali per Node.js, Python, TypeScript, Go, PHP e Java. In Node.js, npm install billionverify-sdk ti fornisce un client con un metodo verify; in Python, il pacchetto è billionverify.

Interpretare la risposta: stato, punteggio e motivo

Il campo status è quello su cui si basano la maggior parte dei rami del codice. Ecco cosa significa ogni stato e un valore predefinito sensato per un modulo di registrazione:

Il campo score fornisce un’indicazione più precisa tra 0 e 1. Come guida approssimativa, i risultati valid hanno un punteggio da 0,85 a 1,0, catchall circa da 0,55 a 0,75, unknown da 0,3 a 0,6, disposable 0,1 e invalid 0. Un risultato role mantiene il punteggio del controllo sottostante. Puoi usare il punteggio per impostare la tua soglia per i casi borderline, ad esempio accettando gli indirizzi catch-all solo sopra un determinato punteggio in un modulo ad alto valore.

Il campo reason spiega il verdetto. Un risultato invalid può includere invalid_syntax, no_mx_records o mailbox_not_found, e ciascuno indica un messaggio diverso da mostrare all’utente. Un problema di sintassi significa «controlla il formato». Una casella mancante significa «questa casella non esiste». La pagina dei motivi della verifica elenca ogni motivo e indica quali motivi unknown vale la pena ritentare.

Due campi aiutano direttamente l’utente: domain_suggestion può alimentare un suggerimento come «Intendevi gmail.com?», mentre is_disposable spiega perché un indirizzo usa e getta è stato rifiutato.

Progettare il flusso di registrazione attorno a un budget di latenza

La parte difficile è inserire il controllo in un modulo senza rallentarlo. Inizia da un budget. Decidi per quanto tempo sei disposto ad attendere l’utente, ad esempio da 300 a 500 millisecondi all’invio. Tutto il resto deriva da quel numero.

Il testo del prodotto BillionVerify indica risultati memorizzati nella cache sotto i 200 ms e un controllo SMTP completo in media da 1 a 3 secondi. Questa differenza ti lascia due buone opzioni:

1. Controllo completo con timeout. Chiama l’API con SMTP attivo e un timeout di 2–3 secondi. La maggior parte delle risposte arriva in tempo e ti fornisce un valore chiaro valid o invalid. Se scatta il timeout, consenti il passaggio e ripeti il controllo in seguito.
2. Controllo rapido ora, controllo approfondito in seguito. Chiama l’API con check_smtp: false. Questo risolve solo i casi evidenti: sintassi errata, un dominio senza record MX, indirizzi usa e getta e indirizzi di ruolo. Un indirizzo su un dominio funzionante restituisce unknown con il motivo smtp_unverifiable, come previsto. Accettalo, poi esegui una seconda chiamata con SMTP attivo da un processo in background. Se la casella di posta non esiste, contrassegna l’account e chiedi all’utente di confermare il proprio indirizzo.

Sono utili anche alcune pratiche frontend:

• Convalida quando il campo perde il focus o all’invio, non a ogni pressione di tasto. Controllare j, jo, joh spreca chiamate e crediti.
• Esegui prima i controlli locali della sintassi per risparmiare un passaggio di rete negli errori evidenti.
• Chiama l’API dal tuo backend. Il server conserva la chiave API e registra il risultato; il browser mostra solo l’esito.

Per dettagli UX come la formulazione, il posizionamento degli errori e quando mostrare un suggerimento, consulta verifica dell’email durante la registrazione.

Fallire in modo sicuro o consentire? Gestire timeout e casi sconosciuti

Il modello che funziona per la maggior parte dei prodotti è: fallire in modo sicuro in caso di errori evidenti, consentire in caso di incertezza.

• Fallire in modo sicuro significa bloccare la registrazione. Fallo quando l’API indica che l’indirizzo è chiaramente errato: invalid con invalid_syntax o no_mx_records, oppure un indirizzo disposable in un modulo in cui gli account usa e getta causano problemi.
• Consentire significa lasciare procedere l’utente e intervenire in seguito. Fallo quando la risposta è incerta: uno stato unknown, un dominio catch-all o il timeout impostato che scatta prima che l’API risponda.

Perché non bloccare anche gli indirizzi incerti? Molte persone reali li utilizzano. I server di posta aziendali spesso applicano il greylisting o limitano la frequenza dei controlli SMTP, quindi bloccarli comporta la perdita di registrazioni reali. Accetta, aggiungi un tag al record e verifica nuovamente in seguito.

Imposta un timeout lato client per la chiamata API che corrisponda al tuo budget di latenza. Quando scatta, tratta il risultato come unknown: accetta, memorizza un flag e accoda una nuova verifica in background. Riprova i risultati unknown in seguito, anziché durante la richiesta.

Esempio: Convalidare un indirizzo email durante la registrazione in Node.js

Lo schema seguente mostra il controllo rapido (design 2) in un gestore di registrazione. Utilizza l’endpoint REST documentato e i campi della risposta, un timeout e le regole di apertura o blocco descritte sopra. Adatta i nomi al tuo framework.

const BLOCK = new Set(['invalid', 'disposable']);

async function checkEmail(email) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 400);

  try {
    const response = await fetch('https://api.billionverify.com/v1/verify/single', {
      method: 'POST',
      headers: {
        'BV-API-KEY': process.env.BV_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, check_smtp: false }),
      signal: controller.signal,
    });
    const body = await response.json();
    if (!body.success) return { allow: true, recheck: true };

    const { status, reason, domain_suggestion } = body.data;
    if (BLOCK.has(status)) {
      return { allow: false, reason, suggestion: domain_suggestion };
    }
    return { allow: true, recheck: status === 'unknown' || status === 'catchall' };
  } catch {
    // Timeout or network error: fail open and re-check in the background.
    return { allow: true, recheck: true };
  } finally {
    clearTimeout(timer);
  }
}

Senza SMTP, la maggior parte degli indirizzi reali restituisce unknown e riceve il flag recheck. Dopo il salvataggio dell’account, un processo in background chiama lo stesso endpoint con SMTP attivo per ogni record contrassegnato con recheck. Il tutorial su Node.js illustra una configurazione più completa, incluso l’SDK ufficiale. La stessa richiesta funziona da Python o da qualsiasi linguaggio con un client HTTP.

Limiti di frequenza, caching e costi

Un controllo in tempo reale viene eseguito durante la registrazione, quindi i suoi limiti diventano i tuoi. Pianifica di conseguenza.

Limiti di frequenza. BillionVerify protegge la propria capacità con limiti per account. Quando ne raggiungi uno, l’API restituisce HTTP 429 con il codice 1003 e un’intestazione Retry-After. Riduci la frequenza e riprova, mantenendo attiva la tua regola fail-open, così un limite non bloccherà mai un utente reale.

Caching. I risultati vengono memorizzati nella cache, per questo i controlli ripetuti restituiscono rapidamente il risultato. Ricontrollare un indirizzo verificato dal tuo account nelle ultime 24 ore è gratuito. Usa force_refresh: true solo quando hai davvero bisogno di una risposta aggiornata, perché salta la cache e viene addebitato come un nuovo controllo.

Costi. Un singolo controllo utilizza normalmente 1 credito, indicato in credits_used. Ogni risultato unknown è gratuito, così come gli errori di sintassi. Convalida al momento dell’invio anziché a ogni pressione di un tasto e non ricontrollare un indirizzo verificato di recente. BillionVerify offre 20 crediti gratuiti ogni giorno in cui effettui l’accesso, fino a 600 al mese: una quantità sufficiente per creare e testare un’integrazione. I pacchetti di crediti a pagamento sono elencati nella pagina dei prezzi.

Oltre il modulo: batch, file e webhook

La validazione in tempo reale verifica i nuovi indirizzi uno alla volta. Per tutto il resto, la stessa API offre altri punti di accesso:

• Batch ridotti. POST /verify/bulk controlla fino a 50 indirizzi in un’unica richiesta, ideale per una sincronizzazione CRM o una schermata di importazione.
• Liste grandi. POST /verify/file accetta un file CSV, TXT o XLSX e lo elabora in background.
• Webhook. Invece di interrogare periodicamente un processo sui file, registra un webhook per gli eventi file.completed e file.failed. Consulta la guida ai webhook per la verifica delle email per i controlli delle firme e i nuovi tentativi.
• Controlli solo usa e getta. POST /verify/disposable risponde solo alla domanda sulla natura usa e getta e non utilizza crediti.

Una configurazione comune: controlli in tempo reale su ogni modulo, un batch notturno per i record contrassegnati con recheck e un processo sui file prima delle campagne di grandi dimensioni.

Checklist per la convalida delle email in tempo reale

Prima del rilascio, passa in rassegna questo elenco:

• La chiave API risiede sul server, mai nel browser.
• La sintassi viene verificata localmente prima della chiamata API.
• Il percorso della richiesta usa check_smtp: false e un timeout adeguato al tuo budget di latenza.
• invalid e disposable hanno messaggi di errore chiari e specifici.
• unknown, catchall e i timeout non bloccano la richiesta e vengono messi in coda per una nuova verifica.
• domain_suggestion fornisce un suggerimento per gli errori di battitura.
• Le risposte 429 applicano un backoff senza bloccare gli utenti.
• I risultati vengono salvati con il record dell’utente, così puoi misurare in seguito i tassi di rimbalzo.

FAQ

Che cos’è un’API di convalida email in tempo reale?

Un’API di convalida email in tempo reale verifica un singolo indirizzo email mentre un utente invia un modulo e restituisce un responso in una frazione di secondo. Esegue controlli di sintassi, dominio, MX, indirizzi temporanei, ruoli e catch-all e, facoltativamente, un controllo della casella SMTP, così la tua app può accettare, bloccare o segnalare l’indirizzo prima che raggiunga il database.

In cosa differisce la convalida email in tempo reale dalla convalida in blocco?

La convalida email in tempo reale verifica un indirizzo alla volta durante una richiesta dell’utente e deve rispondere rapidamente. La convalida in blocco controlla un’intera lista in background e può richiedere molto più tempo. Usa i controlli in tempo reale per mantenere puliti i nuovi dati e i controlli in blocco per pulire i dati che già possiedi.

Devo eseguire il controllo SMTP a ogni registrazione?

Dipende dal tuo budget di latenza. Il controllo SMTP è ciò che conferma l’esistenza di una casella, quindi senza di esso la maggior parte degli indirizzi reali restituisce unknown. Se puoi attendere 2–3 secondi, eseguilo all’invio con un timeout. Altrimenti, esegui il controllo rapido con check_smtp: false e fai il controllo SMTP in un’attività in background.

Cosa devo fare con i risultati catch-all e unknown?

Accettali e ricontrollali in seguito. Un dominio catch-all accetta qualsiasi indirizzo, quindi il controllo della casella non può dimostrare che la posta in arrivo esista, mentre un risultato unknown significa che il controllo non è riuscito a completarsi. Bloccare questi utenti fa perdere registrazioni reali; etichettarli e ricontrollarli mantiene puliti i tuoi dati senza danneggiare il tasso di conversione.

Posso chiamare l’API di controllo email dal browser?

No. In questo modo esporresti la tua API key. Chiama l’API dal tuo backend e restituisci solo la decisione.

Quanto è veloce la verifica email in tempo reale?

Con BillionVerify, i risultati memorizzati nella cache vengono restituiti in meno di 200 ms e un controllo SMTP completo richiede in media 1–3 secondi. Ecco perché il controllo rapido senza SMTP deve essere eseguito durante la richiesta, mentre il controllo SMTP va eseguito in background.

Quanto costa un’API di convalida email?

In BillionVerify, un singolo controllo utilizza normalmente 1 credito e ogni risultato unknown è gratuito. Ricevi 20 crediti gratuiti ogni giorno in cui effettui l’accesso, fino a 600 al mese, mentre i pacchetti di crediti a pagamento sono disponibili nella pagina dei prezzi. force_refresh ignora la cache e viene fatturato come un nuovo controllo.

Inizia a convalidare le email in tempo reale

La convalida delle email in tempo reale significa meno rimbalzi, meno account falsi e meno utenti persi a causa di un errore di battitura. Inserisci un controllo rapido nel percorso della richiesta, sposta il controllo lento in background e lascia che gli errori chiari blocchino la richiesta, mentre i risultati incerti passano. Crea un account BillionVerify gratuito, ottieni una chiave API ed effettua la tua prima chiamata API di convalida email dalla documentazione qui sopra.