Añadir un dominio remitente de correo electrónico

POST /v1/email-sender-domains · permiso email-sender-domains:write · todos los planes

Añade un dominio desde el que puede enviarse el correo de su entorno, firmado con DKIM. El dominio empieza en pending_dns; publique los records devueltos en su DNS y verifique el dominio.

Los dominios remitentes solo pueden añadirse en entornos production, con un máximo de 10 por entorno. El nombre se convierte en una A-label de IDNA 2008 y se elimina el punto final.

Los dos CNAME de DKIM (akp1, akp2) apuntan a claves que mantiene la plataforma, por lo que la rotación de claves nunca requiere un cambio en su DNS. El CNAME de return-path devuelve los rebotes a la plataforma.

Solicitud

Campo	Tipo	Obligatorio	Descripción
`domain`	string	sí	Dominio o subdominio desde el que enviar (se admite Unicode), de 253 caracteres como máximo.
`Idempotency-Key`	header	no	Repite la misma respuesta para una solicitud repetida con la misma clave.

{
  "domain": "mail.example.com"
}

Respuesta

201 Created con el nuevo dominio remitente y ETag con su versión. Los campos se describen en Obtener un dominio remitente de correo electrónico.

{
  "id": "sdom_01k7r9m3q5t8v2w4x6y8z0a2b4",
  "domain": "mail.example.com",
  "status": "pending_dns",
  "active_selector": "akp1",
  "dkim_status": null,
  "return_path_status": null,
  "dmarc_alignment": null,
  "last_checked_at": null,
  "failing_since": null,
  "degraded_since": null,
  "records": [
    {
      "type": "CNAME",
      "name": "akp1._domainkey.mail.example.com",
      "value": "akp1.sdom_01k7r9m3q5t8v2w4x6y8z0a2b4.dkim.eu.keenauth.app",
      "required": true
    },
    {
      "type": "CNAME",
      "name": "akp2._domainkey.mail.example.com",
      "value": "akp2.sdom_01k7r9m3q5t8v2w4x6y8z0a2b4.dkim.eu.keenauth.app",
      "required": true
    },
    {
      "type": "CNAME",
      "name": "rp.mail.example.com",
      "value": "rp.eu.mail.keenauth.app",
      "required": true
    }
  ],
  "version": 1,
  "created_at": "2026-10-19T09:00:00Z",
  "updated_at": "2026-10-19T09:00:00Z"
}

Errores

HTTP	código	Cuándo
409	`conflict`	El dominio ya está añadido a este entorno.
409	`domain_limit_reached`	El entorno ya tiene 10 dominios remitentes.
422	`validation_failed`	`/domain required`: no hay dominio. `/domain invalid`: una dirección IP, una sola etiqueta, un sufijo público (por ejemplo `co.uk`), un dominio de la plataforma (`keenauth.com`, `keenauth.app` y sus subdominios) o un nombre tan largo que su registro DKIM supera los 253 octetos. `/domain production_only`: el entorno no es `production`.
422	`idempotency_key_reuse`	La `Idempotency-Key` se usó con una solicitud distinta.
401	`unauthenticated`	La credencial falta, no es válida o fue revocada.
403	`insufficient_permissions`	La credencial no tiene el permiso requerido.
429	`rate_limited`	Se superó el límite de frecuencia; reintente después del período `Retry-After`.
503	`service_unavailable`	Una dependencia no está disponible temporalmente; reintente después del período `Retry-After`.

Ejemplo

curl -X POST https://api.eu.keenauth.com/v1/email-sender-domains \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2e8a-7d3b-4c9e-a1f0-2b6d8e4c7a90" \
  -d '{"domain":"mail.example.com"}'

CLI: keenauth email-sender-domains create --domain mail.example.com