Verificare un indirizzo email

Una sola chiamata ti dice se un indirizzo accetterà posta. Usala alla registrazione, o prima di agire su un lead, per tenere fuori dal tuo invio gli indirizzi che genererebbero un bounce. Tutto ciò che segue richiede una chiave API con lo scope lookup.

Verificare un indirizzo

const answer = await bird.lookup.email({ email: "aisha.khan@example.com" });
// result is an open vocabulary; delivery_confidence is always comparable.
console.log(answer.result, answer.delivery_confidence);

answer = client.lookup.email(email="aisha.khan@example.com")
# result is an open vocabulary; delivery_confidence is always comparable.
print(answer.result, answer.delivery_confidence)

answer, err := client.Lookup.Email(context.Background(), bird.LookupEmailParams{
	Email: "aisha.khan@example.com",
})
if err != nil {
	log.Fatal(err)
}
// result is an open vocabulary; delivery_confidence is always comparable.
fmt.Println(*answer.Result, *answer.DeliveryConfidence)

$answer = $bird->lookup->email(
    (new EmailLookupRequest())->setEmail('aisha.khan@example.com'),
);
// result is an open vocabulary; delivery_confidence is always comparable.
echo $answer->getResult(), ' ', $answer->getDeliveryConfidence();

bird lookup email --email aisha.khan@example.com

curl -X POST "https://us1.platform.bird.com/v1/lookup/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "aisha.khan@example.com"
  }'

Verificare un batch

Usa POST /v1/lookup/email/batch per valutare fino a 1.000 indirizzi in una sola richiesta:

curl -X POST "https://us1.platform.bird.com/v1/lookup/email/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"emails":["aisha.khan@example.com","not-an-email"]}'

L'array data nella risposta contiene una valutazione per ogni input, nell'ordine di invio. Gli indirizzi malformati ricevono valutazioni individuali. Gli indirizzi duplicati restano voci separate e ogni voce con risposta viene fatturata. Gli spazi circostanti vengono rimossi e le maiuscole/minuscole vengono preservate.

Mantieni ogni richiesta entro 128 KiB. Suddividi le liste più grandi in batch separati. Se attivi i tentativi idempotenti, usa una chiave diversa per ogni batch. Le risposte fino a 256 KiB possono essere conservate per il replay; le risposte più grandi vengono restituite senza protezione dal replay, quindi riprovare può eseguire e addebitare un altro batch. Consulta il riferimento API per i batch.

Come scrivere l'indirizzo

Invia un indirizzo semplice, esattamente come lo conservi. Una lookup su singolo indirizzo rifiuta le forme con display-name come Aisha <aisha@example.com> invece di scomporle. Le lookup in batch restituiscono una valutazione per ogni stringa inviata.

La parte prima della @ viene passata così com'è scritta senza convertirla in minuscolo, e il campo email preserva quel formato. Le risposte batch rimuovono gli spazi circostanti; abbina ogni risultato all'input nella stessa posizione. Invia l'indirizzo con le maiuscole/minuscole che hai invece di normalizzarlo prima: result è generalmente uguale in entrambi i casi, ma delivery_confidence non è sempre identico, quindi cambiare le maiuscole/minuscole può cambiare la risposta che ottieni.

I cinque verdetti

result è il campo su cui decidere.

valid: l'indirizzo esiste e accetta posta. Invia.

neutral: non è stato possibile confermare in nessuna delle due direzioni, di solito perché il dominio di ricezione risponde a ogni destinatario allo stesso modo. Inviare è ragionevole: un indirizzo neutro non è un indirizzo cattivo, è uno senza risposta certa.

risky: probabilmente accetta posta ma ha più probabilità della media di generare un bounce o un reclamo. Indirizzi di ruolo, indirizzi usa e getta e indirizzi con bassa reputazione finiscono qui. Se inviare o meno è una decisione basata sulla tua tolleranza ai reclami, e flags indica di quale tipo di rischio si tratta.

undeliverable: non accetta posta. Non inviare. reason dice perché: invalid_syntax per un indirizzo malformato, invalid_domain quando il dominio non accetta posta, invalid_recipient quando il dominio accetta posta ma questa casella non esiste.

typo: l'indirizzo sembra contenere un errore di battitura, e did_you_mean contiene la correzione. Proponi la correzione a chi ha digitato l'originale invece di inviare direttamente alla correzione: è un'ipotesi, e l'indirizzo che intendevano potrebbe non essere nessuno dei due.

result è un vocabolario aperto, quindi un valore che non riconosci è un verdetto futuro, non un errore. Gestisci i valori che conosci e per il resto affidati a delivery_confidence, che è sempre presente e sempre confrontabile.

Leggi la confidenza insieme al verdetto, non al posto di esso

delivery_confidence va da 0 (consegna certamente non riuscita) a 100 (consegna certa). Lo stesso punteggio può trovarsi sotto neutral o risky per ragioni diverse, quindi è un secondo parere, non un sostituto di result. È il campo su cui basarti quando vuoi un'unica soglia per tutti i verdetti, compresi quelli aggiunti in futuro.

valid contiene la valutazione di validità del provider. Un destinatario non valido può avere valid: false anche quando il suo dominio accetta posta. Usa result e delivery_confidence insieme per decidere se inviare; valid: true non garantisce la consegna.

I flag descrivono il tipo di indirizzo

flags è vuoto quando non si applica nulla di rilevante. Tre valori sono definiti, ed è una lista aperta.

role significa che l'indirizzo identifica una funzione anziché una persona, come support@ o info@. Risposte e consenso sono ambigui, e i reclami sono più probabili.

disposable significa che appartiene a un provider di indirizzi usa e getta, quindi in genere smetterà di esistere.

free_provider significa che appartiene a un provider di caselle consumer come Gmail o Outlook.com. È normale per la posta consumer, e rappresenta un segnale solo se ti aspettavi un indirizzo aziendale.

Riprovare senza pagare due volte

Ogni indirizzo con risposta viene fatturato, undeliverable incluso, perché è la risposta che hai pagato e il bounce che hai evitato. Invia un Idempotency-Key così un nuovo tentativo riproduce il verdetto salvato invece di acquistarne un secondo. Vedi Idempotenza.

La forma GET, che inserisce l'indirizzo nell'URL, non può trasportare una chiave di idempotenza. Usa la forma POST per qualsiasi operazione automatizzata.

Errori

Prossimi passi

• Verificare un numero di telefono è l'altra metà di Lookup.
• Soppressioni impediscono invii ripetuti a indirizzi che hanno già generato un bounce, senza costi.
• Reference di Lookup API documenta ogni campo.
• Verifica email: quell'indirizzo accetterà davvero la posta? è un video che esegue lookup su un indirizzo di ruolo, un errore di battitura e un provider gratuito.