Consultar una dirección de correo electrónico

Una sola llamada te dice si una dirección aceptará correo. Úsala al registrar usuarios, o antes de actuar sobre un prospecto, para evitar que direcciones que rebotarían lleguen a tu envío. Todo lo que se describe aquí requiere una clave API con el alcance lookup.

Consultar una dirección

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

Consultar un lote

Usa POST /v1/lookup/email/batch para evaluar hasta 1000 direcciones en una sola solicitud:

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

El array data de la respuesta contiene una evaluación por entrada, en el orden de envío. Las direcciones mal formadas reciben evaluaciones individuales. Las direcciones duplicadas se mantienen como entradas separadas y cada entrada respondida se factura. Los espacios en blanco alrededor se recortan y las mayúsculas y minúsculas se conservan.

Mantén cada solicitud dentro de 128 KiB. Divide las listas más grandes en lotes separados. Si optas por los reintentos idempotentes, usa una clave distinta para cada lote. Las respuestas de hasta 256 KiB se pueden conservar para reproducción; las respuestas más grandes se devuelven sin protección de reproducción, por lo que reintentar puede ejecutar y cobrar otro lote. Consulta la referencia de API por lotes.

Cómo escribir la dirección

Envía la dirección tal cual, exactamente como la tienes. Una consulta de dirección individual rechaza formatos con nombre visible como Aisha <aisha@example.com> en lugar de extraer la dirección. Las consultas por lote devuelven una evaluación para cada cadena enviada.

La parte antes del @ se pasa tal como está escrita sin convertirla a minúsculas, y el campo email conserva esas mayúsculas y minúsculas. Las respuestas de lote recortan los espacios en blanco alrededor; haz coincidir cada resultado con la entrada en la misma posición. Envía la dirección con las mayúsculas y minúsculas que tengas en lugar de normalizarla primero: result es generalmente igual en ambos casos, pero delivery_confidence no siempre es idéntico, así que cambiar las mayúsculas y minúsculas puede cambiar la respuesta que obtienes.

Los cinco veredictos

result es el campo sobre el que decidir.

valid: la dirección existe y acepta correo. Envía.

neutral: no se pudo confirmar en ningún sentido, normalmente porque el dominio receptor responde igual a todos los destinatarios. Enviar es razonable; una dirección neutral no es una dirección mala, es una que no se puede verificar.

risky: probablemente acepta correo, pero es más propensa que la mayoría a rebotar o generar quejas. Las direcciones de rol, las direcciones desechables y las direcciones de baja reputación caen aquí. Enviar o no es una decisión sobre tu propia tolerancia a las quejas, y flags te indica qué tipo de riesgo es.

undeliverable: no acepta correo. No envíes. reason indica el motivo: invalid_syntax para una dirección mal formada, invalid_domain cuando el dominio no acepta correo en absoluto, invalid_recipient cuando el dominio acepta correo pero este buzón no existe.

typo: la dirección parece tener un error tipográfico, y did_you_mean contiene la corrección. Ofrece la corrección a quien escribió la dirección original en lugar de enviar a ella sin preguntar: es una suposición, y la dirección que querían escribir puede no ser ninguna de las dos.

result es un vocabulario abierto, así que un valor que no reconozcas es un veredicto futuro, no un error. Bifurca según los valores que conozcas y recurre a delivery_confidence, que siempre está presente y siempre es comparable.

Lee la confianza junto al veredicto, no en lugar de él

delivery_confidence va de 0 (certeza de que no se entregará) a 100 (certeza de que sí). La misma puntuación puede estar bajo neutral o risky por razones distintas, así que es una segunda opinión, no un reemplazo de result. Es el campo en el que apoyarte cuando quieres un solo umbral para todos los veredictos, incluidos los que se añadan en el futuro.

valid contiene la evaluación de validez del proveedor. Un destinatario no válido puede tener valid: false incluso cuando su dominio acepta correo. Usa result y delivery_confidence juntos al decidir si enviar; valid: true no garantiza la entrega.

Las flags describen el tipo de dirección

flags está vacío cuando no aplica nada notable. Hay tres valores definidos, y es una lista abierta.

role significa que la dirección nombra una función en lugar de una persona, como support@ o info@. Las respuestas y el consentimiento son ambiguos, y las quejas son más probables.

disposable significa que pertenece a un proveedor de direcciones desechables, así que normalmente dejará de existir.

free_provider significa que pertenece a un proveedor de correo para consumidores como Gmail u Outlook.com. Eso es normal para correo de consumidores, y solo es una señal cuando esperabas una dirección empresarial.

Reintenta sin pagar dos veces

Cada dirección respondida se factura, incluida undeliverable, porque es la respuesta por la que pagaste y el rebote que evitaste. Envía un Idempotency-Key para que un reintento reproduzca el veredicto almacenado en lugar de comprar otro. Consulta Idempotencia.

La forma GET, que pone la dirección en la URL, no puede llevar una clave de idempotencia. Usa la forma POST para cualquier proceso automatizado.

Errores

Próximos pasos

• Consultar un número de teléfono es la otra mitad de Lookup.
• Supresiones evitan envíos repetidos a direcciones que ya rebotaron, sin costo.
• Referencia de Lookup API documenta todos los campos.
• Consulta de email: ¿esa dirección realmente acepta correo? es un video que ejecuta consultas contra una dirección de rol, un error tipográfico y un proveedor gratuito.