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).
{
"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
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 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).