# 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](verify.md) 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. |

```json
{
  "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](get.md).

```json
{
  "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

```bash
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`