# Aggiungi un indirizzo email

`POST /fapi/v1/me/emails` · chiamato dall'host di accesso dell'ambiente

Aggiunge un indirizzo email all'utente autenticato come indirizzo non verificato e non principale, e invia a quell'indirizzo un link di verifica. L'indirizzo diventa utilizzabile quando l'utente apre il link. Ogni richiesta accettata risponde con `202` senza corpo, anche quando l'indirizzo è già uno dei suoi; la risposta non indica mai se l'indirizzo è in uso su un altro account. Un utente può avere al massimo 10 indirizzi, incluso quello principale. Richiede il cookie `__Host-idp_session` dell'utente autenticato; se il cookie manca, è scaduto o è stato revocato, restituisce `401 unauthenticated`. Un'app di prima parte su un'altra origine può invece inviare il proprio token di accesso Front API (`Authorization: DPoP <token>` con una prova DPoP; vedi [Token di accesso Front API](/docs/api/fapi/front-api-token)).

La sessione deve essere stata verificata negli ultimi 5 minuti. Se l'utente ha un secondo fattore, la sessione deve inoltre essere stata aperta con un secondo fattore (`urn:idp:acr:mfa`).

## Richiesta

Intestazioni:

| Intestazione | Obbligatoria | Descrizione |
| --- | --- | --- |
| `Idp-Client` | sì | Identificatore dell'SDK. |
| `Origin` | sì | Deve essere esattamente `https://<sign-in host>`. |
| `Content-Type` | sì | `application/json`. |

Corpo:

| Campo | Tipo | Obbligatorio | Descrizione |
| --- | --- | --- | --- |
| `email` | string | sì | L'indirizzo da aggiungere (al massimo 320 caratteri). |

## Risposta

`202 Accepted`, senza corpo.

## Errori

| Stato | Codice | Quando |
| --- | --- | --- |
| 400 | `malformed_request` | Il corpo non è JSON valido. |
| 400 | `unknown_field` | Il corpo contiene un campo diverso da `email`. |
| 401 | `unauthenticated` | Cookie di sessione assente o non valido. |
| 401 | `step_up_required` | La sessione non è stata verificata negli ultimi 5 minuti oppure è richiesto un secondo fattore; verifica di nuovo con `max_age=300` (e, se applicabile, `acr_values`) nell'intestazione `WWW-Authenticate`. |
| 403 | `origin_not_allowed` | `Origin` manca o è errato. |
| 409 | `email_limit_reached` | L'utente ha già 10 indirizzi email. |
| 413 | `payload_too_large` | Il corpo è troppo grande. |
| 415 | `unsupported_media_type` | `Content-Type` non è `application/json`. |
| 422 | `validation_failed` | `email` manca. |
| 422 | `email_invalid` | `email` non è un indirizzo email valido. |
| 422 | `email_domain_not_allowed` | L'ambiente non consente indirizzi con questo dominio. |
| 429 | `verification_rate_limited` | Sono stati inviati troppi messaggi di verifica di recente; riprova più tardi. |

## Esempio

```bash
curl -X POST https://example.keenauth.app/fapi/v1/me/emails \
  -H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
  -H "Origin: https://example.keenauth.app" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"email": "ada@example.org"}'
```

## Dati personali

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