Dominios y remitentes

Para desarrolladores

Consulte y verifique por la API los dominios y remitentes de su instancia. Crearlos, eliminarlos y enviar la configuración DNS por correo solo se puede hacer desde el panel web.

Alcance

Cubre:

• Consulta y validación de dominios vía los endpoints de integración (API key).
• Consulta y búsqueda de remitentes sobre un dominio verificado vía los endpoints de integración.

Fuera de alcance:

• Gestión de credenciales SMTP — se realiza desde el panel; ver Crear y gestionar credenciales SMTP.

Autenticación

Los endpoints de la tabla siguiente requieren:

• Authorization: Bearer <API_KEY> — API key de la instancia.
• X-Instance-Slug: <slug> — identificador de la instancia.

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.

Dominios (base /v1/domains):

Método	Path	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.

Remitentes (base /v1/senders):

Método	Path	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.

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

Un dominio solo se valida cuando se llama a POST /v1/domains/{id}/validate. La plataforma no lo hace de forma automática ni avisa por webhook o notificación: un dominio recién creado queda en pending hasta que se ejecute esa llamada.

Por eso, consultar GET /v1/domains/{id} una y otra vez no hace avanzar la verificación: el GET solo lee y devuelve siempre el mismo estado. La llamada que hay que repetir es POST /v1/domains/{id}/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 dejó de responder o cambió de valor al momento de esta validación.
cualquierarevoked	La validación actual no genera este estado.

Un dominio verificado puede volver a failed. Si sus registros DNS cambiaron o dejaron de resolver, el estado no se degrada solo: cambia 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. Si queda alguno que apunte a otro servidor (por ejemplo, el del correo corporativo), mx_status no llega 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. Sirve para probar el envío de principio a fin 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.
• 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; por la API se consulta y se verifica 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. Repetir el GET no hace avanzar la verificación: 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

Esto es un 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	El id o el domain_name no existe en la instancia.
422	Un campo está mal formado; la respuesta trae el detalle por campo.

Contrato de referencia

El contrato de referencia es el OpenAPI que publica la propia API: el spec está en https://$API_HOST/openapi.json y la referencia navegable en https://$API_HOST/docs.