# 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 **TypeScript** ```typescript 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); ``` Examples: [TypeScript](/it-it/documentazione/guides/lookup/email-addresses.ts.md) · [Python](/it-it/documentazione/guides/lookup/email-addresses.py.md) · [Go](/it-it/documentazione/guides/lookup/email-addresses.go.md) · [PHP](/it-it/documentazione/guides/lookup/email-addresses.php.md) · [CLI](/it-it/documentazione/guides/lookup/email-addresses.cli.md) · [MCP](/it-it/documentazione/guides/lookup/email-addresses.mcp.md) · [cURL](/it-it/documentazione/guides/lookup/email-addresses.curl.md) ## Verificare un batch Usa `POST /v1/lookup/email/batch` per valutare fino a 1.000 indirizzi in una sola richiesta: ```bash 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](/docs/guides/idempotency), 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](/docs/api/reference/create-email-lookup-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 ` 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](/docs/guides/idempotency). 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 | Codice | Cosa è successo | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`E22003`](/docs/api/errors/E22003) | Una lookup su singolo indirizzo ha ricevuto un indirizzo email non valido. Non è stato addebitato nulla. Le lookup in batch valutano le stringhe malformate individualmente e fatturano tali valutazioni. | | [`E22001`](/docs/api/errors/E22001) | Il wallet dell'organizzazione non può coprire la lookup. Ricaricalo e riprova. Non è stato addebitato nulla. | | [`E22002`](/docs/api/errors/E22002) | La lookup è temporaneamente non disponibile. Riprova con backoff. Non è stato addebitato nulla. | ## Prossimi passi - [Verificare un numero di telefono](/docs/guides/lookup/phone-numbers) è l'altra metà di Lookup. - [Soppressioni](/docs/guides/email/suppressions) impediscono invii ripetuti a indirizzi che hanno già generato un bounce, senza costi. - [Reference di Lookup API](/docs/api/reference/create-email-lookup) documenta ogni campo. - [Verifica email: quell'indirizzo accetterà davvero la posta?](/learn/lookup/email-lookup-will-that-address-actually-accept-mail) è un video che esegue lookup su un indirizzo di ruolo, un errore di battitura e un provider gratuito. ## Related resources - [What are bounced emails?](/explained/deliverability/what-are-bounced-emails) (answer) - [Email lookup](/lookup-api) (product) [Get an implementation brief](/learn/workspace?topic=lookup-email)