# Eine nicht verifizierte zusätzliche E-Mail-Adresse einem Benutzer hinzufügen

`POST /v1/users/{user_id}/emails` · Berechtigung `users:write`

Fügt dem Benutzer eine zusätzliche, nicht verifizierte E-Mail-Adresse hinzu. Die Adresse wird vor dem Speichern normalisiert. Besitzt der Benutzer bereits dieselbe Adresse, wird kein neuer Eintrag geschrieben und der vorhandene Eintrag zurückgegeben (er kann verifiziert oder primär sein), sodass eine Wiederholung der Anfrage unbedenklich ist. Ein neuer Eintrag wird als `user.email_added` im Verwaltungs-Audit-Log protokolliert, wobei der API-Schlüssel als Akteur gilt; die Adresse selbst wird nicht im Audit-Eintrag gespeichert. Um die Adresse zu verifizieren, senden Sie eine Bestätigungs-E-Mail mit `POST /v1/users/{user_id}/emails/{email_id}:send-verification` oder markieren Sie sie mit `:verify` als verifiziert.

## Anfrage

| Parameter | In | Pflicht | Beschreibung |
|---|---|---|---|
| `user_id` | path | ja | Benutzer-ID, mit `usr_` beginnend. |

| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| `email` | string | ja | Die Adresse, höchstens 320 Zeichen. |

## Antwort

`201 Created` mit dem E-Mail-Eintrag. Ohne die Berechtigung `users:read_pii` wird die Adresse maskiert (`a***@e***.com`).

```json
{
  "id": "0191f0a0-3333-7444-8555-666666666666",
  "email": "ada@example.com",
  "verified": false,
  "primary": false,
  "created_at": "2026-01-15T09:30:00Z"
}
```

## Fehler

Jeder Fehler ist ein `application/problem+json`-Body mit einem stabilen `code`.

| HTTP | `code` | Wann |
|---|---|---|
| 400 | `malformed_request`, `unknown_field` | Der Anfragekörper ist kein gültiges JSON oder enthält ein unbekanntes Feld. |
| 409 | `conflict` | Die Adresse ist bei einem anderen Benutzer dieser Umgebung verifiziert (`errors[]`: `/email`, `email_taken`). |
| 409 | `email_limit_reached` | Der Benutzer hat bereits 10 Adressen. |
| 415 | `unsupported_media_type` | Der Anfragekörper wurde ohne `Content-Type: application/json` gesendet. |
| 422 | `validation_failed` | `email` fehlt, ist leer, länger als 320 Zeichen, keine gültige Adresse oder hat den falschen Typ. |
| 404 | `not_found` | Der Benutzer existiert in dieser Umgebung nicht, wird gerade gelöscht oder die ID ist fehlerhaft. |
| 401 | `unauthenticated` | Der API-Schlüssel fehlt, ist ungültig oder wurde widerrufen. |
| 403 | `insufficient_permissions` | Dem Schlüssel fehlt die Berechtigung `users:write`. |
| 429 | `rate_limited` | Das Ratenlimit wurde überschritten; beachten Sie `Retry-After`. |
| 503 | `service_unavailable` | Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage später. |

## Beispiel

```bash
curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/emails \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com"}'
```

## Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Profil des Endbenutzers. [Personenbezogene Daten in den KeenAuth-APIs](/docs/policies/personal-data) beschreibt, was gespeichert wird, wie lange es aufbewahrt wird und wie es gelöscht wird. Übermitteln Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).