# E-Mail-Absender-Domain hinzufügen

`POST /v1/email-sender-domains` · Berechtigung `email-sender-domains:write` · alle Tarife

Fügt eine Domain hinzu, von der aus die E-Mails Ihrer Umgebung gesendet werden können, signiert mit DKIM. Die Domain beginnt mit dem Status `pending_dns`. Veröffentlichen Sie die zurückgegebenen `records` in Ihrem DNS und [verifizieren](verify.md) Sie die Domain.

Absender-Domains können nur in `production`-Umgebungen hinzugefügt werden, höchstens 10 pro Umgebung. Der Name wird in ein IDNA-2008-A-Label umgewandelt, und ein abschließender Punkt wird entfernt.

Die beiden DKIM-CNAMEs (`akp1`, `akp2`) verweisen auf Schlüssel, die die Plattform verwaltet. Eine Schlüsselrotation erfordert daher auf Ihrer Seite nie eine DNS-Änderung. Der Return-Path-CNAME leitet Bounces an die Plattform zurück.

## Anfrage

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `domain` | string | ja | Domain oder Subdomain, von der aus gesendet wird (Unicode erlaubt), höchstens 253 Zeichen. |
| `Idempotency-Key` | header | nein | Gibt bei einer wiederholten Anfrage mit demselben Schlüssel dieselbe Antwort zurück. |

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

## Antwort

`201 Created` mit der neuen Absender-Domain und `ETag` mit deren Version. Die Felder sind unter [Eine E-Mail-Absender-Domain abrufen](get.md) beschrieben.

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

## Fehler

| HTTP | Code | Wann |
|---|---|---|
| 409 | `conflict` | Die Domain ist dieser Umgebung bereits hinzugefügt. |
| 409 | `domain_limit_reached` | Die Umgebung hat bereits 10 Absender-Domains. |
| 422 | `validation_failed` | `/domain required`: keine Domain. `/domain invalid`: eine IP-Adresse, ein einzelnes Label, ein Public Suffix (zum Beispiel `co.uk`), eine Plattform-Domain (`keenauth.com`, `keenauth.app` und deren Subdomains) oder ein Name, dessen DKIM-Eintragsname mehr als 253 Oktette umfasst. `/domain production_only`: die Umgebung ist nicht `production`. |
| 422 | `idempotency_key_reuse` | Der `Idempotency-Key` wurde mit einer anderen Anfrage verwendet. |
| 401 | `unauthenticated` | Der Berechtigungsnachweis fehlt, ist ungültig oder widerrufen. |
| 403 | `insufficient_permissions` | Dem Berechtigungsnachweis fehlt die erforderliche Berechtigung. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach der Wartezeit `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach der Wartezeit `Retry-After`. |

## Beispiel

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