Una API para validar email es, en el fondo, una consulta de servidor a servidor: mandás una dirección con tu clave privada y recibís una respuesta por cada comprobación que se hizo. Lo que más confunde no es la llamada sino la respuesta. ByeBouncer no devuelve un “bueno o malo” ni un puntaje; devuelve qué se comprobó, qué se pudo confirmar y qué quedó sin determinar. Esta guía te muestra cómo leer cada parte para decidir en tu sistema.
Preparar la consulta a la API de validación de email
El endpoint es POST /api/v1/verify-email, con cuerpo JSON {"email": "..."}. La clave va en el header Authorization como Bearer. Para validar desde tu backend usá una clave bb_live_…; las claves bb_pub_… existen para el widget del navegador y están pensadas para ese uso, no para tu servidor. Si querés la respuesta separada por dato y sin puntaje, agregá ?result_format=validation-v1 a la URL. Sin ese parámetro conservás el formato anterior, que se mantiene por compatibilidad con integraciones existentes.
curl -X POST "https://api.byebouncer.com/api/v1/verify-email?result_format=validation-v1" \
-H "Authorization: Bearer $BB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"persona@ejemplo.com"}'Cada verificación consume 1 crédito, incluso si el resultado salió de caché. Eso te conviene tenerlo en cuenta en formularios: validá una vez al enviar y no en cada tecla. Los errores son los de una API común: 400 si el cuerpo es inválido, 401 si la clave falta o no es válida, 402 si no quedan créditos y 429 si superaste el límite de pedidos (viene con un header Retry-After).
Leer el resultado: deliverability y checks
La respuesta en validation-v1 trae execution_status (completed o partial) y un bloque results.email. Ahí importan tres cosas. La primera es deliverability, que solo toma tres valores: deliverable, undeliverable o undetermined. La segunda es checks, un objeto con una entrada por comprobación (sintaxis, servidor de correo del dominio, SMTP, catálogo de descartables). La tercera es attributes, con datos descriptivos como el proveedor de alojamiento inferido o si el dominio exige SMTPUTF8.
Cada check tiene un state: completed, not_requested, not_applicable, unavailable o failed. Es la diferencia clave con una API de “sí/no”: un check unavailable no significa que la dirección esté mal, significa que esa comprobación no se pudo hacer. Y cuando hay un reason, te dice por qué. Por ejemplo, null_mx indica que el dominio declara explícitamente que no recibe correo, mientras que un fallo de DNS temporal queda como no disponible y nunca como “el buzón no existe”.
- undeliverable: el dominio no recibe correo, la sintaxis es inválida o el servidor rechazó ese destinatario concreto. Es el único caso donde conviene frenar sin dudar.
- deliverable: el servidor aceptó al destinatario. Es una señal, no una garantía de entrega, de bandeja de entrada ni de que la persona lea el mensaje.
- undetermined: no hay base para afirmar ni negar. Ni lo trates como válido ni lo descartes por reflejo.
Un ejemplo recortado y ficticio de cómo se ve una dirección sin determinar: deliverability llega como undetermined, checks.syntax figura completed con valor true, checks.mail_server figura completed con valor true y checks.smtp figura unavailable con el motivo provider_blocked. Leído junto, dice algo preciso: la dirección está bien escrita y el dominio recibe correo, pero el proveedor no dejó confirmar ese buzón. Con un único campo “estado” esa información se perdería, y ese es el motivo de fondo por el que conviene mirar los checks y no solo el veredicto.
Qué hacer con las respuestas sin determinar
Hay dos causas habituales. Una es técnica y transitoria: un timeout, un servidor que responde con un error temporal o un greylisting (el servidor rechaza el primer intento a propósito y acepta el reintento). El estándar SMTP, en la RFC 5321, distingue respuestas 4xx, temporales, de 5xx, permanentes, y ese matiz es el que justifica reintentar unas y no otras. La otra es de configuración del destino: un servidor catch-all acepta cualquier destinatario, así que su aceptación no demuestra que el buzón exista, y algunos proveedores bloquean las pruebas de SMTP sin dar una respuesta útil.
En la práctica, una política razonable para un alta de usuario sería: si es undeliverable, pedí corregir el correo; si es undetermined, aceptá el registro y mandá un mail de confirmación, que es la única prueba real de que la persona controla ese buzón; si es deliverable, seguí normal. Para una campaña masiva puede ser distinto: ahí muchos equipos prefieren excluir los undetermined del primer envío y reintentarlos más tarde. Esa decisión es tuya; la API te da la evidencia, no la regla.
Integrarlo sin exponer la clave
- Hacé la llamada desde tu backend. Una clave bb_live_ en el JavaScript del navegador está a un “ver código fuente” de quedar pública.
- Guardala en una variable de entorno o en un gestor de secretos, nunca en el repositorio.
- Poné un timeout corto y decidí qué pasa si la API no responde: lo más sano suele ser dejar pasar el alta y verificar después, en lugar de bloquear a un usuario por una falla ajena.
- Respetá el Retry-After cuando recibas un 429 y no reintentes en bucle.
- Guardá el resultado junto con la fecha de la observación: la validez de un correo cambia con el tiempo y un dato de hace un año ya no vale lo mismo.
Lo que esta API no hace
Conviene decirlo sin vueltas. ByeBouncer no devuelve un puntaje global ni decide si alguien es auténtico, un bot o un fraude. Que un servidor acepte al destinatario no prueba entrega, titularidad ni consentimiento. El catálogo de dominios descartables solo detecta coincidencias exactas con listas conocidas: que no haya coincidencia no garantiza que el correo sea de una persona real. Y los datos del dominio (SPF, DMARC, antigüedad) describen al dominio, no al buzón. Con esos límites claros, el resultado sirve para filtrar basura y ordenar prioridades, no para reemplazar tu criterio.
Ver cómo funciona la verificación de correos →
Crear una cuenta y probar la API →
Consultar la documentación de la API →