Verificar un dominio

POST /api/v1/domains/{domainId}/verify Pide al proveedor de correo que vuelva a leer el DNS y guarda la respuesta. Requiere el rol Admin. Es la llamada que hay que repetir tras publicar tus registros, no GET /api/v1/domains, que devuelve el último estado conocido. La propagación tarda hasta 72 horas, normalmente minutos.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERRechazado — 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.

Parámetros de ruta

ParámetroTipoDescripción
domainIdstringObligatorio. El dominio que se vuelve a comprobar

Ejemplo

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/domains/$DOMAIN_ID/verify"

Respuesta

  • 200 OK: la llamada tuvo éxito.
  • 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.
  • 404 Not Found: no existe ese recurso, o pertenece a otra organización. La API nunca confirma que un id existe a quien no tiene derecho sobre él.
  • 429 Too Many Requests: más de 120 peticiones en un minuto para esta clave.

Campos de la respuesta

El dominio tras la comprobación, con la misma forma que al leerlo.
No se gana nada publicando dos veces. Sondea este endpoint hasta que verified sea true; ante una caída del proveedor responde con un error en lugar de un estado desactualizado, porque la verificación es exactamente lo que se pidió.
CampoTipoDescripción
successbooleanIndica si la operación tuvo éxito
data.idstringIdentificador del dominio declarado
data.domainstringEl dominio en sí
data.dkimStatusstringPENDING, SUCCESS o FAILED: las claves de firma
data.mailFromStatusstring \null
data.mailFromDomainstring \null
data.verifiedbooleanLa única pregunta que decide el envío: DKIM en SUCCESS y propiedad probada
data.ownershipProvedbooleanCuál de los dos gestos falta todavía
data.lastCheckedAtstring \null
data.sesUnavailablebooleantrue significa que estás leyendo el último estado conocido, no la verdad actual
data.dnsRecordsarrayLos registros que publicar: {type, name, value, purpose}

Ejemplo de respuesta

json
{
  "success": true,
  "data": {
    "id": "4d19c0a2",
    "domain": "mail.example.com",
    "dkimStatus": "SUCCESS",
    "mailFromStatus": "SUCCESS",
    "mailFromDomain": "bounce.mail.example.com",
    "verified": true,
    "ownershipProved": true,
    "lastCheckedAt": "2026-08-23T10:22:05.000Z",
    "sesUnavailable": true,
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "abc123._domainkey.mail.example.com",
        "value": "abc123.dkim.amazonses.com",
        "purpose": "dkim"
      }
    ]
  }
}

Receta para agentes

Declarar un dominio, publicar sus registros y verificarlo es un ciclo que un agente puede ejecutar de principio a fin. La propagación tarda de minutos a 72 horas, así que espacia los intentos en lugar de insistir sin pausa.
js
const {data: domain} = await (
  await fetch(`${base}/domains`, {
    method: 'POST',
    headers: {...headers, 'content-type': 'application/json'},
    body: JSON.stringify({domain: 'mail.example.com'}),
  })
).json()

await publishToDns(domain.dnsRecords) // tu registrador, tu API

for (let wait = 30_000; wait < 3_600_000; wait *= 2) {
  const {data} = await (
    await fetch(`${base}/domains/${domain.id}/verify`, {method: 'POST', headers})
  ).json()

  if (data.verified) break
  if (!data.ownershipProved) console.log('DKIM is fine — the TXT challenge is what is missing')
  await new Promise((resolve) => setTimeout(resolve, wait))
}

Relacionado