Saltar al contenido principal

Listar dominios

GET/v1/domains

Descripción​

Retorna una lista paginada de dominios registrados en la instancia.

Autenticación​

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

Request​

Query params:

domainstring | null
Filtra por nombre de dominio - coincidencia parcial, insensible a mayúsculas. Ver Filtros de texto.
is_verifiedboolean | null
true retorna únicamente dominios donde las cuatro verificaciones DNS (MX, SPF, DKIM, DMARC) están aprobadas. false retorna todo lo demás: cualquier dominio con al menos una verificación en un estado distinto de verified, lo que incluye pending, failed y también revoked. Omitido: sin filtro.
pageinteger
Página, 1-indexed. Default: 1.
page_sizeinteger
Tamaño de página, 1–100. Default: 20.

Response​

200 OKDevuelve una página de resultados: data con los elementos y pagination para pedir la siguiente. Cada elemento tiene 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

El listado incluye el dominio del entorno de pruebas provisionado con la cuenta, identificable por is_sandbox: true. No lo registró el cliente y no requiere publicar registros DNS; ver El dominio del entorno de pruebas. El envelope {data, pagination} es el estándar de toda colección de la API — semántica completa en Paginación y formato de respuesta.

Cada elemento tiene los mismos campos que GET /v1/domains/{id}.

Request
curl -X GET "https://$API_HOST/v1/domains?is_verified=true&page=1&page_size=20" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"
Response
{
"data": [
  {
    "id": 7,
    "domain": "correos.micomercio.cl",
    "mx_status": "verified",
    "...": "..."
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": 1,
  "total_pages": 1
}
}