Sign inGet started

Dominios de envío

Antes de que podamos entregar correo desde tu dominio, tienes que demostrar que eres su propietario y publicar los registros DNS que permiten a los proveedores de buzón autenticar tu correo. Un dominio de envío es el recurso con alcance de espacio de trabajo (dom_...) que registra esa configuración: qué registros publicar, qué se ha verificado y si el dominio está listo para enviar.

Compartir un dominio entre organizaciones

Un mismo dominio puede ser registrado por más de una organización sin que ninguna interfiera con las demás. Cada organización demuestra la propiedad con su propia clave DKIM, así que:
  • Otra organización en el mismo dominio nunca puede ver tu estado de verificación ni cambiar tu configuración.
  • Cada región (us1, eu1) es independiente: el mismo dominio en dos regiones son dos registros separados con sus propios registros DNS. Regístralo en cada región desde la que envíes.

Registrar un dominio

Crea el dominio con POST /v1/email/domains. La llamada tiene alcance de espacio de trabajo y recibe el dominio de envío más etiquetas opcionales para los nombres de host de return-path y tracking. Pasa solo la etiqueta (send, links) y componemos el nombre de host completo bajo tu dominio de envío. Los valores omitidos toman por defecto send y links.
Usa un subdominio dedicado (mail.acme.com) en lugar de tu dominio registrado. Mantiene tu reputación de envío separada de todo lo demás en el dominio y mantiene cada registro que te pedimos publicar fuera del apex de tu zona. Esa segunda razón es la que causa problemas: el registro MX para recepción se ubica en el mismo nombre que los registros MX que ya transportan el correo de tu empresa, así que en un dominio de envío en el apex publicarlo redirige ese correo hacia nosotros.
const domain = await bird.domains.create({ domain: "mail.acme.com" });
console.log(domain.id, domain.status); // "dom_…", "pending"
La respuesta incluye status: pending, el selector DKIM asignado a tu organización y los dns_records que debes publicar. Un registro de espacio de trabajo existente devuelve 409. Superar la cuota de dominios de tu organización devuelve 422. Reemplaza eu1 con us1 para un espacio de trabajo en EE. UU. Las claves API usan los mismos prefijos regionales: bk_eu1_... y bk_us1_.... También puedes gestionar dominios en Email > Domains.
La página Domains en el panel, mostrando un dominio de envío verificado con sus capacidades de envío, return-path y tracking

Publicar los registros DNS

El array dns_records te proporciona name, host y value listos para copiar y pegar de cada registro. Algunos proveedores rechazan un valor TXT DKIM largo como una sola cadena; el divisor de registros DNS lo divide en las cadenas entrecomilladas que esos proveedores esperan. Lo que publicas:
RegistroTipoRequerido para envíoQué hace
DKIMTXTDemuestra la propiedad y firma tu correo con la clave de tu organización
Return-path CNAMECNAMEEnruta los rebotes de vuelta hacia nosotros y cubre SPF; la consulta SPF sigue el CNAME, por lo que no se necesita un registro SPF en el apex de tu dominio
DMARCTXTCualquier política v=DMARC1 válida que cubra el dominio de envío, en el propio dominio o en su dominio registrado (organizacional). Una política p=none mínima es suficiente.
Tracking CNAMECNAMENoHabilita nombres de host de tracking de aperturas/clics con tu marca; los enlaces rastreados se sirven sobre HTTPS una vez que se verifica
MX de entradaMXNoEnruta el correo del dominio hacia nosotros para recepción. Lleva optional: true hasta que habilites la recepción; publicarlo reemplaza los registros MX que el dominio usa actualmente.
Para el propósito y los valores de cada registro, consulta DKIM, SPF y DMARC. Los registros MX de recepción están en dns_records con purpose: inbound_mx siempre que la recepción esté disponible en tu región, y llevan optional: true hasta que habilites la recepción en el dominio. Omite cada registro marcado como optional a menos que quieras lo que habilita. Para pasos de configuración según el proveedor de DNS, consulta las guías de Cloudflare, Route 53 o registrador genérico.
El panel detecta proveedores de DNS compatibles a partir de los servidores de nombres de tu dominio y enlaza a su configuración DNS. Abre Email > Domains y selecciona un dominio para ver sus registros. Si otra persona gestiona tu DNS, POST /v1/email/domains/{domain_id}/dns-records/share les envía por correo los registros que deben publicar.
La página DNS Records de un dominio en el panel, mostrando el registro DKIM verificado con nombre y valor copiables, seguido de las secciones de return-path y DMARC

Ciclo de vida de verificación

Un dominio nuevo comienza como pending. No necesitas hacer polling porque verificamos tus registros automáticamente. Las comprobaciones empiezan de inmediato tras el registro y pasan de cada par de minutos a cada hora durante los primeros tres días. Después se ejecutan diariamente para cada dominio activo. Publicar tus registros y esperar es suficiente; la mayoría de los dominios se verifican en minutos tras la propagación DNS. Si quieres una comprobación inmediata (por ejemplo, justo después de editar el DNS), llama a POST /v1/email/domains/{domain_id}/verify: ejecuta una comprobación nueva y devuelve el dominio actualizado. Un 200 con registros aún pending no es un fallo; significa que los registros aún no se encontraron, lo cual es normal mientras el DNS se propaga (de minutos a horas). La llamada se puede repetir sin problema mientras esperas.
Un dominio que permanece sin verificar durante unos 14 días se elimina. Enviamos un recordatorio por correo al espacio de trabajo unos días antes de la eliminación para que puedas completar la configuración.
El status de nivel superior del dominio refleja la propiedad, demostrada por el registro DKIM:
  • pending: el registro DKIM aún no se ha publicado.
  • verified: el registro DKIM está en su lugar; la propiedad está confirmada.
  • failed: existe un registro DKIM pero no coincide con el valor esperado, o se eliminó un registro verificado anteriormente. Corrige el registro para recuperarlo.
  • temporary_failure: la resolución DNS falló de forma transitoria; la verificación se reintenta automáticamente.
  • rejected: el dominio fue rechazado por razones de política; contacta con soporte.
La disponibilidad para enviar se reporta por separado bajo capabilities. La puerta de envío es capabilities.sending, que se verifica solo cuando DKIM, el CNAME de return-path y una política DMARC están todos en su lugar; SPF en el apex del dominio no es requerido. La disponibilidad de tracking (capabilities.tracking) es independiente de la puerta de envío: controla si se puede usar el tracking de aperturas/clics con tu marca, nunca si el dominio puede enviar.

Cuando un registro verificado se rompe

La verificación nunca se detiene: la recomprobación diaria mantiene honestos a los dominios verificados, así que si tu DNS se rompe después, lo detectamos. Para evitar oscilaciones por fallos DNS transitorios, un registro verificado que empieza a fallar en sus recomprobaciones se mantiene verificado en estado de advertencia y se recomprueba cada hora, y te notificamos. Solo después de que el registro haya seguido fallando durante 24 horas completas se degrada el dominio; cualquier comprobación exitosa dentro de esa ventana elimina la advertencia. Las degradaciones surten efecto en el siguiente envío, y un dominio degradado se reverifica automáticamente una vez que los registros se corrigen, en la siguiente comprobación automática o en una verificación manual.

Gestión de dominios

Regiones. El estado del dominio es regional. Si envías desde us1 y eu1, registra el dominio en cada región; cada registro obtiene su propio selector DKIM y se verifica de forma independiente.
Cambiar nombres de host de return-path o tracking. Estos nombres de host pertenecen a la configuración de dominio de tu espacio de trabajo. Un nombre de host que ya se verificó nunca se reemplaza por uno sin verificar: los cambios se preparan, se verifican junto a tu configuración activa y se promueven solo cuando los nuevos registros pasan la comprobación.
Tracking de aperturas/clics. Los toggles settings pertenecen a la configuración de dominio del espacio de trabajo. Los cambios en los toggles aplican solo a esta configuración de dominio. Puedes activarlos en cuanto se configure un dominio de tracking. Habilitar uno sin un dominio de tracking devuelve un 409. Los toggles afectan los envíos solo después de que ese dominio de tracking se verifique, así que la verificación se aplica por envío.
Eliminación. DELETE /v1/email/domains/{domain_id} elimina el dominio de envío de tu espacio de trabajo. Los demás usos del dominio no se ven afectados.

Próximos pasos