Consulta de dirección de email
Un solo campo para decidir sobre una dirección.
Envía una dirección y obtén un veredicto: valid, neutral, risky, undeliverable o typo. Junto a él, una puntuación de confianza de 0 a 100, las flags que indican qué tipo de dirección es y la dirección que un error tipográfico parece haber querido ser. Una sola solicitud, sin listas que subir ni tareas que consultar.
const answer = await bird.lookup.email({
email: "aisha.khan@exampel.com",
});
console.log(answer.result, answer.delivery_confidence);
// → "typo" 31
console.log(answer.did_you_mean);
// → "aisha.khan@example.com"
console.log(answer.valid, answer.flags);
// → true []
Un veredicto sobre el que puedes ramificar tu lógica.
No un porcentaje para el que tengas que elegir un umbral.
La consulta de dirección de email es una de las dos operaciones de la Bird Lookup API. El campo sobre el que escribir tu lógica es result, porque ya reduce las comprobaciones de sintaxis, dominio, buzón y reputación a cinco resultados. delivery_confidence está disponible para los casos en los que quieres calificar en lugar de bloquear, por ejemplo retener un registro de riesgo para revisión en vez de rechazarlo. La dirección que envías es la dirección que recibes de vuelta: la parte local distingue mayúsculas y minúsculas y no se convierte a minúsculas, y el formato display-name se rechaza en lugar de parsearse.
Seis campos y para qué sirve cada uno.
Todos llegan con la misma solicitud.
- 01
result, el veredicto.
valid es seguro para enviar. neutral es entregable sin nada que lo recomiende. risky probablemente aceptará correo y conlleva una razón para dudar. undeliverable no puede recibir correo. typo parece un error tipográfico de una dirección real.
- 02
reason, solo donde aplica.
invalid_syntax, invalid_domain o invalid_recipient, indicando cuál de las tres comprobaciones no superó la dirección. Solo está presente en el veredicto undeliverable y en ningún otro, así que su ausencia también es información.
- 03
did_you_mean, la corrección.
La dirección que un typo parece ser un error tipográfico, lista para mostrar a la persona que la escribió. Un formulario de registro que ofrece la corrección recupera la cuenta en lugar de perderla por un rebote que nadie ve.
- 04
delivery_confidence, de 0 a 100.
Una calificación en lugar de una decisión, que es lo que lo diferencia de result. Dos direcciones pueden compartir un veredicto y estar muy separadas en este número, y esa diferencia es donde encaja una cola de revisión.
- 05
flags, el tipo de dirección.
role para un buzón compartido como info o support, disposable para un proveedor de correo desechable y free_provider para un buzón de consumidor. Las tres son direcciones bien formadas que aceptan correo, por eso son flags y no veredictos.
- 06
valid, el booleano estricto.
Si la dirección está bien formada y su dominio puede recibir correo en absoluto. No dice nada sobre el buzón, por lo que es true para muchas direcciones cuyo veredicto es risky. Cuando te refieras al veredicto, lee result.
Cinco resultados, cuatro acciones.
Rechaza las undeliverable, ofrece la corrección en un typo, retén una dirección risky para revisión y acepta el resto. Esa es toda la integración, y cabe en el handler de envío del formulario que recoge la dirección.
const answer = await bird.lookup.email({
email: "info@example.com",
});
if (answer.result === "undeliverable") {
// reason is present on this verdict and no other.
reject(answer.reason);
} else if (answer.result === "typo") {
suggest(answer.did_you_mean);
} else if (answer.result === "risky") {
// A role or disposable address is well formed and still a poor signup.
review(answer.flags);
} else {
accept(answer.delivery_confidence);
}
Lo que cuesta y lo que no es.
Una dirección por solicitud, y cada veredicto se factura, incluido undeliverable, porque llegar a ese veredicto es el trabajo. No hay formato por lotes ni carga de listas. Un reintento con el mismo Idempotency-Key reproduce el veredicto que ya pagaste. Lookup tampoco es una lista de supresión: te dice cómo se ve una dirección antes de enviar, mientras que la supresión registra lo que pasó después, y una configuración de envío saludable usa ambas.
Profundiza en la documentación.
Consultar una dirección de email recorre la solicitud y cada campo de la respuesta. La descripción general de Lookup cubre ambas operaciones en una sola página, límites de tasa documenta el grupo de lookup e idempotencia explica lo que cuesta un veredicto reproducido.
Preguntas sobre direcciones de email, respondidas.
Los veredictos, las flags, la puntuación de confianza y dónde encaja la supresión.
¿Qué responde una consulta de dirección de correo electrónico?
¿Cuáles son los cinco veredictos?
¿Por qué una dirección es undeliverable?
¿Qué debo hacer con un veredicto typo?
¿En qué se diferencia delivery_confidence de result?
También hay un campo valid. ¿Es lo mismo que el veredicto valid?
¿Qué significan los indicadores?
¿Cómo debo escribir la dirección?
¿Necesito Lookup para dejar de enviar a direcciones que ya rebotaron?
Ponlo en práctica.
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
El resto de Lookup
Una API key, un mismo formato de error. Explora la otra funcionalidad.
Verifica una dirección antes de que llegue a tu lista.
Una sola llamada en tu handler de registro mantiene los rebotes, las cuentas desechables y los errores tipográficos fuera de la base de datos.