Declarar un dominio

POST /api/v1/domains Declara un dominio de envío y crea la identidad de envío que sus registros probarán. Requiere el rol Admin. Es el primer paso de un ciclo pensado para automatizarse: declarar, leer los registros, publicarlos y luego verificar hasta que verified sea true.

Autorización

Rol en la organización	Este endpoint
`OWNER`	Permitido
`ADMIN`	Permitido
`MEMBER`	Rechazado — `403`

Una clave lleva el rol que su creador tiene en esta organización, nunca un rol en AgentsMail en sí. Consulta Claves de API.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`domain`	string	sí	El dominio o subdominio desde el que enviar, p. ej. `mail.example.com`

Ejemplo

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "mail.example.com"}' \
  "https://www.agentsmail.io/api/v1/domains"

Respuesta

201 Created: el recurso creado.
400 Bad Request: la validación falló; details lleva los problemas campo por campo.
401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.
403 Forbidden: el propietario de la clave es member de la organización, no admin.
429 Too Many Requests: más de 120 peticiones en un minuto para esta clave.

Campos de la respuesta

201 con el dominio declarado y los registros que publicar.

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación tuvo éxito
`data.id`	string	Identificador del dominio declarado
`data.domain`	string	El dominio en sí
`data.dkimStatus`	string	`PENDING`, `SUCCESS` o `FAILED`: las claves de firma
`data.mailFromStatus`	string \	null
`data.mailFromDomain`	string \	null
`data.verified`	boolean	La única pregunta que decide el envío: DKIM en `SUCCESS` y propiedad probada
`data.ownershipProved`	boolean	Cuál de los dos gestos falta todavía
`data.lastCheckedAt`	string \	null
`data.sesUnavailable`	boolean	`true` significa que estás leyendo el último estado conocido, no la verdad actual
`data.dnsRecords`	array	Los registros que publicar: `{type, name, value, purpose}`

Ejemplo de respuesta

json

{
  "success": true,
  "data": {
    "id": "b71f…",
    "domain": "mail.example.com",
    "dkimStatus": "PENDING",
    "verified": false,
    "ownershipProved": false,
    "dnsRecords": [
      {"type": "CNAME", "name": "abc123._domainkey.mail.example.com", "value": "abc123.dkim.amazonses.com", "purpose": "dkim"}
    ]
  }
}