Aggiungi un indirizzo email secondario non verificato a un utente

POST /v1/users/{user_id}/emails · autorizzazione users:write

Aggiunge all'utente un indirizzo email secondario, non verificato. L'indirizzo viene normalizzato prima di essere memorizzato. Se l'utente ha già lo stesso indirizzo, non viene scritta alcuna riga e viene restituita quella esistente (che può essere verificata o principale), quindi ripetere la richiesta è sicuro. Una nuova riga viene scritta nel log di audit della gestione come user.email_added con la chiave API come attore; l'indirizzo stesso non viene scritto nel record di audit. Per verificare l'indirizzo, invia un'email di verifica con POST /v1/users/{user_id}/emails/{email_id}:send-verification oppure segnalalo come verificato con :verify.

Richiesta

Parametro In Obbligatorio Descrizione
user_id path sì ID dell'utente, con prefisso usr_.
Campo Tipo Obbligatorio Descrizione
email string sì L'indirizzo, al massimo 320 caratteri.

Risposta

201 Created con la riga email. Senza l'autorizzazione users:read_pii l'indirizzo viene mascherato (a***@e***.com).

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

Errori

Ogni errore è un corpo application/problem+json con un code stabile.

HTTP code Quando
400 malformed_request, unknown_field Il corpo non è JSON valido oppure contiene un campo sconosciuto.
409 conflict L'indirizzo è verificato su un altro utente di questo ambiente (errors[]: /email, email_taken).
409 email_limit_reached L'utente ha già 10 indirizzi.
415 unsupported_media_type Il corpo è stato inviato senza Content-Type: application/json.
422 validation_failed email manca, è vuoto, supera 320 caratteri, non è un indirizzo valido o ha un tipo errato.
404 not_found L'utente non esiste in questo ambiente, è in fase di eliminazione, oppure l'ID è malformato.
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha l'autorizzazione users:write.
429 rate_limited È stato superato il limite di richieste; rispetta Retry-After.
503 service_unavailable Una dipendenza non è temporaneamente disponibile; riprova più tardi.

Esempio

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

Dati personali

Questo endpoint contiene dati personali: profilo dell'utente finale. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene eliminato. Non inviare in nessun campo categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale).