# Aggiungi un dominio mittente email

`POST /v1/email-sender-domains` · autorizzazione `email-sender-domains:write` · tutti i piani

Aggiunge un dominio da cui l'email del tuo ambiente può essere inviata, firmata con DKIM. Il dominio inizia con stato `pending_dns`; pubblica i `records` restituiti nel tuo DNS e [verifica](verify.md) il dominio.

I domini mittenti possono essere aggiunti solo negli ambienti `production`, al massimo 10 per ambiente. Il nome viene convertito in un A-label IDNA 2008 e il punto finale viene rimosso.

I due CNAME DKIM (`akp1`, `akp2`) puntano a chiavi detenute dalla piattaforma, quindi la rotazione delle chiavi non richiede mai una modifica DNS da parte tua. Il CNAME return-path riporta i rimbalzi alla piattaforma.

## Richiesta

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `domain` | string | sì | Dominio o sottodominio da cui inviare (sono ammessi caratteri Unicode), al massimo 253 caratteri. |
| `Idempotency-Key` | header | no | Ripropone la stessa risposta per una richiesta ripetuta con la stessa chiave. |

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

## Risposta

`201 Created` con il nuovo dominio mittente e `ETag` impostato alla sua versione. I campi sono descritti in [Ottieni un dominio mittente email](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"
}
```

## Errori

| HTTP | code | Quando |
|---|---|---|
| 409 | `conflict` | Il dominio è già aggiunto a questo ambiente. |
| 409 | `domain_limit_reached` | L'ambiente ha già 10 domini mittenti. |
| 422 | `validation_failed` | `/domain required`: manca il dominio. `/domain invalid`: un indirizzo IP, una singola etichetta, un suffisso pubblico (per esempio `co.uk`), un dominio della piattaforma (`keenauth.com`, `keenauth.app` e i loro sottodomini) oppure un nome così lungo che il nome del record DKIM supera 253 ottetti. `/domain production_only`: l'ambiente non è `production`. |
| 422 | `idempotency_key_reuse` | `Idempotency-Key` è stata usata con una richiesta diversa. |
| 401 | `unauthenticated` | La credenziale manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha l'autorizzazione richiesta. |
| 429 | `rate_limited` | È stato superato il limite di richieste; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza è temporaneamente non disponibile; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

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