Dominios y remitentes

Endpoints para listar, consultar y verificar dominios y remitentes programáticamente. El panel web usa endpoints privados equivalentes en alta/listado/validación/baja (ver Endpoints privados (dashboard)), pero no son las mismas rutas — y solo el panel puede crear o eliminar un dominio o remitente, o enviar la configuración DNS por email.

Alcance

Cubre:

• Consulta y validación de dominios vía los endpoints de integración (API key). El alta y la baja de un dominio son exclusivas del panel web — ver Endpoints privados (dashboard).
• Consulta y búsqueda de remitentes sobre un dominio verificado vía los endpoints de integración. El alta y la baja de un remitente son exclusivas del panel web.

Fuera de alcance:

• Gestión de credenciales SMTP — ver familia /smtp_credential en Referencia de la API pública.
• Detalle del modelo de datos (columnas, constraints) — ver.
• Flujo operativo interno — ver.

Autenticación

Para clientes programáticos (integraciones de backend, scripts, automatizaciones): usar los endpoints de integración de la tabla siguiente. Requieren:

• Authorization: Bearer FD.<key_id>.<token> — API key del tenant.
• X-Instance-Slug: <tenant-slug>.

Para operaciones realizadas por un operador humano desde el panel web: ver Endpoints privados (dashboard).

Ver Referencia de la API pública para el detalle.

Endpoints de integración

Una ficha por endpoint, con request/response tipados, query params y errores — ver.

Dominios (base /v1/domains):

Método	Ruta	Ficha
GET	/v1/domains	Listado
GET	/v1/domains/{id}	Detalle por id
GET	/v1/domains/{domain_name}/status	Estado por nombre
POST	/v1/domains/{id}/validate	Verificación DNS

No existe alta ni baja de dominios bajo /v1/domains — ambas son exclusivas del panel web, que las opera por la superficie privada (POST y DELETE /v1/private/domains).

Remitentes (base /v1/senders):

Método	Ruta	Ficha
GET	/v1/senders	Listado
GET	/v1/senders/{id}	Detalle por id
GET	/v1/senders/search/names	Búsqueda por nombre
GET	/v1/senders/search/emails	Búsqueda por email

No existe alta ni baja de remitentes bajo /v1/senders — ambas son exclusivas del panel web, que las opera por la superficie privada (POST y DELETE /v1/private/senders).

Ciclo de vida de la verificación

Un dominio no tiene un estado, tiene cuatro independientes: mx_status, spf_status, dkim_status y dmarc_status. Cada uno vale pending, verified, failed o revoked. El campo is_verified es derivado: es true solo cuando los cuatro están en verified simultáneamente, y es la condición que habilita crear remitentes y enviar.

La única operación que cambia los estados es POST /validate

La plataforma nunca valida por su cuenta. No hay job de fondo, ni reintento programado, ni webhook, ni notificación. Un dominio recién creado queda en pending y permanece ahí para siempre si nadie ejecuta POST /v1/domains/{id}/validate.

De ahí se sigue lo más importante para quien integra: pollear GET /domains/{id} no sirve para esperar la verificación. El GET es solo lectura y devuelve el mismo estado indefinidamente. Lo que hay que repetir es el POST .../validate.

Qué hace cada validación

Cada llamada consulta el DNS en ese momento y reescribe los cuatro estados con lo que encuentra. Las verificaciones son independientes entre sí: el éxito parcial es normal y esperable (por ejemplo MX verificado y DKIM aún no).

Transición	Cuándo ocurre
pendingverified	La validación encuentra el registro correctamente publicado.
pendingfailed	La validación no encuentra el registro, o lo encuentra con un valor que no corresponde.
failedverified	Una validación posterior lo encuentra ya corregido.
verifiedfailed	Degradación. El registro dejaba de responder o cambió de valor al momento de esta validación.
cualquierarevoked	Estado administrativo. No lo produce la validación.

La degradación es la transición que suele sorprender: un dominio verificado puede volver a failed si se reejecuta la validación después de que sus registros DNS cambiaron o dejaron de resolver. No ocurre sola; ocurre en la siguiente validación que se ejecute.

La propiedad del dominio es informativa

El registro ownership_cname acredita la propiedad y se comprueba una sola vez: cuando pasa, ownership_verified_at queda con fecha y las validaciones siguientes ya no lo consultan. No condiciona la verificación ni el envío - un dominio con los cuatro registros verificados funciona aunque nunca se haya publicado el CNAME de propiedad.

El MX debe ser exclusivo de la plataforma

La verificación de MX exige que todos los registros MX del dominio apunten a la plataforma. Basta con que quede un MX corporativo para que mx_status nunca llegue a verified.

Es la razón práctica por la que conviene usar un subdominio dedicado al envío (envios.tudominio.cl, mail.tudominio.cl) en vez del dominio principal: el dominio raíz normalmente ya tiene MX del correo corporativo, y apuntarlos a la plataforma redirigiría el correo entrante de la organización. Un subdominio dedicado no tiene ese conflicto y permite publicar los cinco registros sin tocar la configuración existente.

El dominio del entorno de pruebas

Cada cuenta recibe automáticamente un dominio de pruebas, identificable por is_sandbox: true en cualquier respuesta que devuelva un dominio. No lo creaste tú: viene provisionado con la cuenta para poder probar el envío end-to-end sin verificar un dominio propio.

Su comportamiento difiere del resto:

• Llega verificado desde el primer día; no requiere publicar ningún registro DNS.
• Validarlo siempre resulta verificado, sin consultar DNS.
• No se puede crear, eliminar ni modificar. Registrar un dominio bajo sandbox.test se rechaza con 422.
• Solo puede enviar a destinatarios del entorno de pruebas. Un envío desde su remitente hacia una casilla real se rechaza con 409.

Flujo programático recomendado

El alta de un dominio y de un remitente son exclusivas del panel web (ver Endpoints privados (dashboard)) — un cliente programático consulta y verifica sobre lo que ya existe:

1. Dar de alta el dominio desde el panel web. Se recomienda un subdominio dedicado, por el motivo explicado en El MX debe ser exclusivo de la plataforma.
2. Presentar al usuario los registros DNS a publicar, tomados de dns_records en GET /v1/domains/{id} (o de GET /v1/domains).
3. Reintentar POST /v1/domains/{id}/validate cada 30-60 s, o exponer un botón Validar que lo ejecute. Pollear el GET no sirve: los estados solo cambian con esta operación (ver Ciclo de vida de la verificación). La propagación DNS puede tardar desde minutos hasta varias horas según el proveedor y el TTL previo.
4. Cuando is_verified=true, dar de alta el remitente desde el panel web.
5. Usar email_address del remitente creado (visible en GET /v1/senders) como sender_email en POST /v1/mails/send.

Para probar el envío antes de tener un dominio propio verificado, se puede usar directamente el remitente del dominio de pruebas, que ya viene verificado con la cuenta.

Errores comunes

Resumen — el detalle completo, con el código exacto por endpoint, está en la ficha de cada uno y en Respuestas de error.

Código HTTP	Caso típico
404	id/domain_name no existe en el tenant.

Ninguno de estos endpoints emite 400: los campos mal formados los rechaza la validación del schema, que responde 422 con el detalle por campo.

Endpoints privados (dashboard)

Estos endpoints son de uso interno del panel web oficial. Requieren JWT de usuario (Authorization: Bearer <jwt>) y no forman parte del contrato público de integración. Se documentan aquí solo como referencia.

Base domains: /v1/domains. Base senders: /v1/senders.

Método	Ruta	Propósito
POST	/v1/domains	Alta (o reactivación si el dominio fue eliminado antes).
GET	/v1/domains	Lista con filtros.
POST	/v1/domains/{id}/validate	Verificación DNS.
POST	/v1/domains/{id}/send-dns-config	Envía los registros DNS por email a un administrador DNS externo.
DELETE	/v1/domains/{id}	Baja.
POST	/v1/senders	Alta.
GET	/v1/senders	Lista con filtros.
GET	/v1/senders/{sender_email}/stats	Estadísticas de entrega del remitente en un período.
DELETE	/v1/senders/{id}	Baja.
GET	/v1/senders/search/names?q=...	Autocomplete por nombre.
GET	/v1/senders/search/emails?q=...	Autocomplete por dirección.

Nota: el panel no expone un GET /v1/domains/{id} de detalle por id — el detalle por id es exclusivo de los endpoints de integración (/v1/domains/{id}).

El contrato autoritativo es el OpenAPI publicado por la propia API en https://$API_HOST/docs (y https://$API_HOST/openapi.json). Este documento reformatea para lectores humanos, pero ante discrepancia el contrato OpenAPI manda.