Validar el DNS de un dominio

POST/v1/domains/{id}/validate

Descripción

Consulta los registros DNS publicados y actualiza los estados de verificación MX, SPF, DKIM y DMARC. Debe ejecutarse después de publicar los registros de dns_records y cada vez que se modifiquen, para reflejar el estado real.

Cada verificación es independiente — el éxito parcial es válido (por ejemplo, MX verificado y SPF fallido).

Es la única operación que cambia los estados de un dominio. La plataforma no valida por su cuenta: no hay job de fondo ni webhook, así que un dominio permanece en pending mientras nadie ejecute esta llamada. Ver Ciclo de vida de la verificación.

Autenticación

Authorizationbearer tokenheaderobligatorio: API key con scope domains:write. Formato: Bearer FD.<key_id>.<token>.
X-Instance-Slugstringheaderobligatorio

Request

Path params:

idinteger: Identificador del dominio.

Response

200 OKDevuelve un objeto con los campos que siguen.

idintegerobligatorio: Identificador del dominio.
domainstringobligatorio: Nombre de dominio normalizado.
mx_statusstring, enum: `pending | verified | failed | revoked`obligatorio: Estado de verificación del registro MX.
mx_verified_atstring (date-time) | nullobligatorio: Fecha de la última validación de este registro, exitosa o no. null solo mientras no se haya ejecutado ninguna validación; después no vuelve a null.
spf_statusstring, enum: `pending | verified | failed | revoked`obligatorio: Estado de verificación del registro SPF.
spf_verified_atstring (date-time) | nullobligatorio: Análogo a mx_verified_at, para SPF.
dkim_statusstring, enum: `pending | verified | failed | revoked`obligatorio: Estado de verificación de los registros DKIM.
dkim_verified_atstring (date-time) | nullobligatorio: Análogo a mx_verified_at, para DKIM.
dmarc_statusstring, enum: `pending | verified | failed | revoked`obligatorio: Estado de verificación del registro DMARC.
dmarc_verified_atstring (date-time) | nullobligatorio: Análogo a mx_verified_at, para DMARC.
ownership_tokenstringobligatorio: Token único usado en dns_records.ownership_cname para probar la propiedad del dominio.
ownership_verified_atstring (date-time) | nullobligatorio: Se comporta distinto a los cuatro anteriores: se escribe una sola vez, cuando la propiedad se acredita, y permanece en null mientras no se haya acreditado.
last_verification_atstring (date-time) | nullobligatorio: Fecha de la última vez que se ejecutó la verificación DNS (exitosa o no). null si nunca se ejecutó.
created_atstring (date-time)obligatorio: —
updated_atstring (date-time)obligatorio: —
is_verifiedbooleanobligatorio: true únicamente cuando mx_status, spf_status, dkim_status y dmarc_status son verified simultáneamente.
is_ownership_verifiedbooleanobligatorio: Equivalente a ownership_verified_at is not null. Es informativo: no condiciona la verificación ni el envío.
is_sandboxbooleanobligatorio: true en el dominio del entorno de pruebas provisionado con la cuenta. Siempre false en un dominio registrado por el cliente. Ver El dominio del entorno de pruebas.
dns_recordsobjectobligatorio: Los registros exactos a publicar — ver tabla siguiente. Se calculan en cada respuesta a partir de los valores de infraestructura de la plataforma; el cliente no necesita consultarlos aparte.

dns_records (cada uno es un objeto {type, host, value, priority}):

ownership_cnameobjeto: Acredita la propiedad del dominio. Es informativo: no condiciona la verificación ni el envío, y se comprueba una sola vez. priority siempre null.
mxobjeto: Enruta los mensajes de bounce hacia la plataforma. La verificación exige que este sea el único MX del dominio (ver el gotcha del MX). Único registro con priority no nulo (10).
spfobjeto: Autoriza a la plataforma a enviar en nombre de este dominio. priority siempre null.
dkimarray, exactamente 2 elementos: Los dos CNAME de firma DKIM (selectores s1, s2). Ambos deben publicarse: uno firma y el otro queda disponible para rotar la llave sin interrumpir envíos. El CNAME es obligatorio — copiar el TXT al que apunta quedaría fijado a la llave vigente y dejaría de verificar en la próxima rotación. priority siempre null.
dmarcobjeto: Registro de política DMARC. Mínimo recomendado: p=none con un rua válido. priority siempre null.

Nota

Mismos campos que GET /v1/domains/{id}, con los cuatro *_status/*_verified_at y last_verification_at actualizados según el resultado de esta verificación.

Errores

Código	Cuándo
404	No existe un dominio con ese `id` en la instancia (`domain_not_found`).

Detalle en Errores genéricos.

Notas

La operación es reintentable: puede invocarse cuantas veces haga falta y, para un mismo estado del DNS, deja el dominio en el mismo resultado. No es libre de efectos: cada llamada reescribe los timestamps de verificación y propaga el estado resultante.
Puede degradar un dominio ya verificado. El resultado refleja lo que el DNS responde en ese momento, así que un dominio con los cuatro registros en verified vuelve a failed si sus registros dejaron de resolver o cambiaron de valor. La degradación no ocurre sola: ocurre en la siguiente validación que se ejecute.
Sobre el dominio del entorno de pruebas (is_sandbox: true) siempre resulta verificado, sin consultar DNS.

Request

curl -X POST "https://$API_HOST/v1/domains/7/validate" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"id": 7,
"domain": "correos.micomercio.cl",
"mx_status": "pending",
"spf_status": "pending",
"dkim_status": "pending",
"dmarc_status": "pending",
"mx_verified_at": null,
"spf_verified_at": null,
"dkim_verified_at": null,
"dmarc_verified_at": null,
"ownership_token": "4ad93f2c49bd30afe3df3a88b401985e",
"ownership_verified_at": null,
"last_verification_at": null,
"is_verified": false,
"is_ownership_verified": false,
"is_sandbox": false,
"created_at": "2026-05-08T14:22:31Z",
"updated_at": "2026-05-08T14:22:31Z",
"dns_records": {
  "ownership_cname": {
    "type": "CNAME",
    "host": "_fidelizador-verify.correos.micomercio.cl",
    "value": "4ad93f2c49bd30afe3df3a88b401985e.fidelizador-verify.com",
    "priority": null
  },
  "mx": {
    "type": "MX",
    "host": "correos.micomercio.cl",
    "value": "<dominio MX de bounce de la plataforma>",
    "priority": 10
  },
  "spf": {
    "type": "TXT",
    "host": "correos.micomercio.cl",
    "value": "v=spf1 include:<dominio SPF de la plataforma> -all",
    "priority": null
  },
  "dkim": [
    {
      "type": "CNAME",
      "host": "s1._domainkey.correos.micomercio.cl",
      "value": "s1._domainkey.<dominio de publicación de la plataforma>",
      "priority": null
    },
    {
      "type": "CNAME",
      "host": "s2._domainkey.correos.micomercio.cl",
      "value": "s2._domainkey.<dominio de publicación de la plataforma>",
      "priority": null
    }
  ],
  "dmarc": {
    "type": "TXT",
    "host": "_dmarc.correos.micomercio.cl",
    "value": "v=DMARC1;p=none;rua=<dirección de reporte DMARC>",
    "priority": null
  }
}
}

Descripción​

Autenticación​

Request​

Response​

Errores​

Descripción

Autenticación

Request

Response

Errores