Vérifier une adresse e-mail

Un seul appel vous indique si une adresse accepte le courrier. Utilisez-le à l'inscription, ou avant d'exploiter un prospect, pour écarter dès le départ les adresses qui provoqueraient un rebond. Tout ce qui suit nécessite une clé API avec le scope lookup.

Vérifier une adresse

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"
  }'

Vérifier un lot

Utilisez POST /v1/lookup/email/batch pour évaluer jusqu'à 1 000 adresses en une seule requête :

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"]}'

Le tableau data de la réponse contient une évaluation par entrée, dans l'ordre de soumission. Les adresses mal formées reçoivent chacune leur propre évaluation. Les adresses en double restent des entrées distinctes et chaque entrée traitée est facturée. Les espaces environnants sont supprimés et la casse est conservée.

Limitez chaque requête à 128 Kio. Découpez les listes plus volumineuses en lots distincts. Si vous activez les réessais idempotents, utilisez une clé différente pour chaque lot. Les réponses jusqu'à 256 Kio peuvent être conservées pour rejeu ; les réponses plus volumineuses sont renvoyées sans protection de rejeu, et un nouvel essai peut donc exécuter et facturer un autre lot. Consultez la référence du lot API.

Comment écrire l'adresse

Envoyez une adresse brute, exactement telle que vous la détenez. Une vérification d'adresse unique rejette les formes avec nom d'affichage telles que Aisha <aisha@example.com> au lieu de les décortiquer. Les vérifications par lot renvoient une évaluation pour chaque chaîne soumise.

La partie avant le @ est transmise telle quelle plutôt que convertie en minuscules, et le champ email conserve cette casse. Les réponses par lot suppriment les espaces environnants ; faites correspondre chaque résultat à l'entrée à la même position. Envoyez l'adresse dans la casse que vous détenez plutôt que de la normaliser d'abord : result est généralement identique dans les deux cas, mais delivery_confidence ne l'est pas toujours, donc changer la casse peut changer la réponse obtenue.

Les cinq verdicts

result est le champ sur lequel vous appuyer pour décider.

valid : l'adresse existe et accepte le courrier. Envoyez.

neutral : impossible de confirmer dans un sens ou dans l'autre, généralement parce que le domaine destinataire répond de la même façon pour tous les destinataires. L'envoi est raisonnable ; une adresse neutre n'est pas une mauvaise adresse, c'est une adresse sans réponse possible.

risky : l'adresse accepte probablement le courrier mais risque davantage de rebondir ou de générer une plainte. Les adresses de rôle, les adresses jetables et les adresses à faible réputation se retrouvent ici. Envoyer ou non relève de votre tolérance aux plaintes, et flags vous indique le type de risque.

undeliverable : l'adresse n'accepte pas le courrier. N'envoyez pas. reason en donne la raison : invalid_syntax pour une adresse mal formée, invalid_domain quand le domaine n'accepte aucun courrier, invalid_recipient quand le domaine accepte le courrier mais que cette boîte aux lettres n'existe pas.

typo : l'adresse semble mal orthographiée, et did_you_mean contient la correction. Proposez la correction à la personne qui a saisi l'original plutôt que d'envoyer directement à cette adresse : c'est une supposition, et l'adresse visée peut n'être ni l'une ni l'autre.

result est un vocabulaire ouvert : une valeur que vous ne reconnaissez pas est un futur verdict, pas une erreur. Branchez sur les valeurs que vous connaissez et repliez-vous sur delivery_confidence, qui est toujours présent et toujours comparable.

Lisez la confiance en complément du verdict, pas à sa place

delivery_confidence va de 0 (certitude de non-livraison) à 100 (certitude de livraison). Le même score peut se trouver sous neutral ou risky pour des raisons différentes : c'est un deuxième avis, pas un remplacement de result. C'est le champ à utiliser quand vous voulez un seuil unique pour tous les verdicts, y compris ceux ajoutés ultérieurement.

valid contient l'évaluation de validité du fournisseur. Un destinataire invalide peut avoir valid: false même quand son domaine accepte le courrier. Utilisez result et delivery_confidence ensemble pour décider d'envoyer ou non ; valid: true ne garantit pas la livraison.

Les flags décrivent le type d'adresse

flags est vide quand rien de notable ne s'applique. Trois valeurs sont définies, et c'est une liste ouverte.

role signifie que l'adresse désigne une fonction plutôt qu'une personne, comme support@ ou info@. Les réponses et le consentement sont ambigus, et les plaintes sont plus probables.

disposable signifie qu'elle appartient à un fournisseur d'adresses jetables : elle cessera généralement d'exister.

free_provider signifie qu'elle appartient à un fournisseur de messagerie grand public tel que Gmail ou Outlook.com. C'est normal pour du courrier grand public, et ne constitue un signal que si vous attendiez une adresse professionnelle.

Réessayer sans payer deux fois

Chaque adresse traitée est facturée, undeliverable compris, car c'est la réponse que vous avez payée et le rebond que vous avez évité. Envoyez un Idempotency-Key pour qu'une nouvelle tentative rejoue le verdict stocké au lieu d'en acheter un second. Consultez Idempotence.

La forme GET, qui place l'adresse dans l'URL, ne peut pas porter de clé d'idempotence. Utilisez la forme POST pour tout ce qui est automatisé.

Erreurs

Étapes suivantes

• Vérifier un numéro de téléphone est l'autre volet de Lookup.
• Suppressions empêchent les envois répétés aux adresses ayant déjà rebondi, sans frais.
• Référence Lookup API documente chaque champ.
• Recherche d'e-mail : cette adresse accepte-t-elle vraiment les messages ? est une vidéo qui lance des vérifications sur une adresse de rôle, une faute de frappe et un fournisseur gratuit.