# Invia un'email di prova

`POST /v1/email-templates/{family}/{locale}:test-send` · autorizzazione `email-templates:write` · piano Startup e superiori

Genera una versione di un template email con gli stessi dati di esempio di [preview](preview.md) e la invia a un indirizzo attraverso il normale percorso di consegna, così puoi verificarla in una casella reale. L'oggetto inizia con `[TEST] `. Il template viene validato di nuovo prima dell'invio.

Regole:

- Il destinatario deve essere un indirizzo email verificato di un membro `active` del tuo account dashboard. Qualsiasi altro indirizzo viene rifiutato e non viene mai ripetuto nella risposta o nei log.
- Ogni ambiente può inviare al massimo 20 email di prova al giorno UTC. La ventunesima viene rifiutata con `429` fino al giorno UTC successivo (`Retry-After` indica l'attesa in secondi).
- La lista di soppressione si applica comunque. Se il destinatario è soppresso, il messaggio viene registrato con stato `suppressed`, non viene consegnato e conta comunque nel limite giornaliero.
- L'ambiente deve poter inviare template personalizzati: un invio di prova viene rifiutato quando la modalità di consegna è `platform_default` oppure l'invio è limitato o sospeso.
- Ogni invio di prova accettato viene scritto nel log di audit di gestione come `email_template.test_sent`, con famiglia, locale e versione ma senza il destinatario.

## Parametri di percorso

| Parametro | Descrizione |
|---|---|
| `family` | Famiglia di email, per esempio `verify_email` o `email_otp` (vedi [Elenca i template email](list.md)). |
| `locale` | Tag di locale, per esempio `en` o `de`. |

## Header

| Header | Descrizione |
|---|---|
| `Idempotency-Key` | Facoltativo, da 16 a 64 caratteri di `A-Z a-z 0-9 _ -`. Ripetere una richiesta con la stessa chiave restituisce il primo messaggio e non lo invia né lo conta di nuovo. Gli SDK e la CLI lo impostano per te. |

## Richiesta

| Campo | Tipo | Descrizione |
|---|---|---|
| `to` | string | Obbligatorio. Il destinatario: un indirizzo verificato di un membro `active` della dashboard, senza nome visualizzato. Maiuscole/minuscole e spazi iniziali o finali vengono ignorati. |
| `version` | integer | La versione salvata da inviare (1 o superiore). Predefinita: la versione più recente. |
| `published` | boolean | `true` invia la versione pubblicata. Non può essere combinato con `version`. |

## Risposta

`200 OK`

```json
{
  "message_id": "0199f3c4-5d6e-7a8b-9c0d-1e2f3a4b5c6d",
  "state": "queued",
  "version": 3,
  "accepted_at": "2026-10-19T09:00:00Z"
}
```

| Campo | Descrizione |
|---|---|
| `message_id` | L'identificatore del messaggio. |
| `state` | `queued` (sarà inviato a breve) oppure `suppressed` (il destinatario è nella lista di soppressione). Una richiesta ripetuta restituisce lo stato attuale del primo messaggio, che può essere anche `sent`, `failed` o `expired`. |
| `version` | La versione che è stata inviata. |
| `accepted_at` | Momento in cui il messaggio è stato accettato. |

## Errori

| HTTP | code | Quando |
|---|---|---|
| 400 | `unknown_field` | Il body contiene un campo sconosciuto oppure non è un oggetto JSON. |
| 400 | `malformed_request` | Il body non è JSON valido, oppure `Idempotency-Key` è malformato o ripetuto. |
| 401 | `unauthenticated` | La credenziale manca, non è valida o è stata revocata. |
| 403 | `insufficient_permissions` | La credenziale non ha l'autorizzazione richiesta. |
| 403 | `plan_feature_unavailable` | Il piano dell'ambiente non include i template email personalizzati (Startup e superiori; `required_plan` indica quale). |
| 404 | `not_found` | La famiglia o il locale è sconosciuto, la versione non esiste, oppure è impostato `published` e non c'è nulla di pubblicato. |
| 409 | `email_template_not_deliverable` | La modalità di consegna o lo stato di invio dell'ambiente non permette di inviare template personalizzati. |
| 422 | `validation_failed` | `to` manca o non è un indirizzo email semplice, `version` è inferiore a 1, sono stati inviati sia `version` sia `published` (`conflicts_with_published`), oppure la versione non supera più la validazione. |
| 422 | `template_forbidden_construct` | La versione usa un costrutto Liquid non consentito nella sandbox. |
| 422 | `test_recipient_not_allowed` | Il destinatario non è un indirizzo verificato di un membro `active` della dashboard. |
| 429 | `rate_limited` | L'ambiente ha già inviato 20 email di prova in questo giorno UTC, oppure è stato superato il limite di frequenza dell'API; riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `test_recipient_source_unavailable` | Il destinatario non può essere verificato al momento; non è stato inviato nulla. Riprova dopo il periodo indicato in `Retry-After`. |
| 503 | `service_unavailable` | Una dipendenza non è disponibile temporaneamente; riprova dopo il periodo indicato in `Retry-After`. |

## Esempio

```bash
curl -X POST https://api.eu.keenauth.com/v1/email-templates/verify_email/en:test-send \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-send-verify-email-en-0001" \
  -d '{"to":"you@example.com","version":3}'
```

CLI: `keenauth email-templates test-send verify_email en --to you@example.com --version 3`

## Dati personali

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