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 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).
`locale`	Tag di locale, per esempio `en` o `de`.

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

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

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 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.