# Ajouter un domaine d'envoi d'e-mails

`POST /v1/email-sender-domains` · autorisation `email-sender-domains:write` · tous les forfaits

Ajoute un domaine depuis lequel les e-mails de votre environnement peuvent être envoyés, signé avec DKIM. Le domaine commence à `pending_dns` ; publiez les `records` renvoyés dans votre DNS et [vérifiez](verify.md) le domaine.

Les domaines d'envoi ne peuvent être ajoutés que dans les environnements `production`, à raison de 10 au maximum par environnement. Le nom est converti en A-label IDNA 2008 et le point final est supprimé.

Les deux CNAME DKIM (`akp1`, `akp2`) pointent vers des clés détenues par la plateforme ; la rotation des clés ne nécessite donc jamais de modification DNS de votre part. Le CNAME return-path achemine les rebonds vers la plateforme.

## Requête

| Champ | Type | Requis | Description |
|---|---|---|---|
| `domain` | string | oui | Domaine ou sous-domaine depuis lequel envoyer (Unicode autorisé), 253 caractères au maximum. |
| `Idempotency-Key` | header | non | Rejoue la même réponse pour une requête répétée avec la même clé. |

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

## Réponse

`201 Created` avec le nouveau domaine d'envoi et `ETag` défini sur sa version. Les champs sont décrits dans [Récupérer un domaine d'envoi d'e-mails](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"
}
```

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 409 | `conflict` | Le domaine est déjà ajouté à cet environnement. |
| 409 | `domain_limit_reached` | L'environnement compte déjà 10 domaines d'envoi. |
| 422 | `validation_failed` | `/domain required` : aucun domaine. `/domain invalid` : une adresse IP, un label unique, un suffixe public (par exemple `co.uk`), un domaine de la plateforme (`keenauth.com`, `keenauth.app` et leurs sous-domaines) ou un nom si long que le nom de son enregistrement DKIM dépasse 253 octets. `/domain production_only` : l'environnement n'est pas `production`. |
| 422 | `idempotency_key_reuse` | La `Idempotency-Key` a été utilisée avec une requête différente. |
| 401 | `unauthenticated` | L'identifiant est absent, invalide ou révoqué. |
| 403 | `insufficient_permissions` | L'identifiant ne dispose pas de l'autorisation requise. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après la période indiquée par `Retry-After`. |
| 503 | `service_unavailable` | Une dépendance est temporairement indisponible ; réessayez après la période indiquée par `Retry-After`. |

## Exemple

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