# 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 **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](/es-es/documentacion/guides/lookup/email-addresses.ts.md) · [Python](/es-es/documentacion/guides/lookup/email-addresses.py.md) · [Go](/es-es/documentacion/guides/lookup/email-addresses.go.md) · [PHP](/es-es/documentacion/guides/lookup/email-addresses.php.md) · [CLI](/es-es/documentacion/guides/lookup/email-addresses.cli.md) · [MCP](/es-es/documentacion/guides/lookup/email-addresses.mcp.md) · [cURL](/es-es/documentacion/guides/lookup/email-addresses.curl.md) ## Consultar un lote Usa `POST /v1/lookup/email/batch` para evaluar hasta 1000 direcciones en una sola solicitud: ```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"]}' ``` 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](/docs/guides/idempotency), 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](/docs/api/reference/create-email-lookup-batch). ## 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 ` 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](/docs/guides/idempotency). 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 | Código | Qué ocurrió | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`E22003`](/docs/api/errors/E22003) | Una consulta de dirección individual recibió una dirección de correo no válida. No se cobró nada. Las consultas por lote evalúan las cadenas mal formadas individualmente y facturan esas evaluaciones. | | [`E22001`](/docs/api/errors/E22001) | El monedero de la organización no puede cubrir la consulta. Recárgalo y reintenta. No se cobró nada. | | [`E22002`](/docs/api/errors/E22002) | La consulta no está disponible temporalmente. Reintenta con retroceso exponencial. No se cobró nada. | ## Próximos pasos - [Consultar un número de teléfono](/docs/guides/lookup/phone-numbers) es la otra mitad de Lookup. - [Supresiones](/docs/guides/email/suppressions) evitan envíos repetidos a direcciones que ya rebotaron, sin costo. - [Referencia de Lookup API](/docs/api/reference/create-email-lookup) documenta todos los campos. - [Consulta de email: ¿esa dirección realmente acepta correo?](/learn/lookup/email-lookup-will-that-address-actually-accept-mail) es un video que ejecuta consultas contra una dirección de rol, un error tipográfico y un proveedor 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)