Envoyer un e-mail de test

POST /v1/email-templates/{family}/{locale}:test-send · autorisation email-templates:write · forfait Startup et supérieurs

Fait le rendu d'une version d'un modèle d'e-mail avec les mêmes données d'exemple que preview et l'envoie à une adresse via le chemin d'envoi habituel, afin que vous puissiez la vérifier dans une véritable boîte de réception. L'objet commence par [TEST] . Le modèle est de nouveau validé avant l'envoi.

Règles :

Le destinataire doit être une adresse e-mail vérifiée d'un membre active de votre compte du tableau de bord. Toute autre adresse est refusée, et l'adresse n'est jamais répétée dans la réponse ni dans les journaux.
Chaque environnement peut envoyer au plus 20 e-mails de test par jour UTC. Le 21e est refusé avec 429 jusqu'au jour UTC suivant (Retry-After indique l'attente en secondes).
La liste de suppression s'applique toujours. Si le destinataire est supprimé, le message est enregistré avec l'état suppressed, n'est pas remis et compte tout de même dans la limite quotidienne.
L'environnement doit envoyer des modèles personnalisés : un envoi de test est refusé lorsque le mode d'envoi est platform_default ou lorsque l'envoi est restreint ou suspendu.
Chaque envoi de test accepté est écrit dans le journal d'audit de gestion sous email_template.test_sent, avec la famille, la langue et la version, mais sans le destinataire.

Paramètres de chemin

Paramètre	Description
`family`	Famille d'e-mails, par exemple `verify_email` ou `email_otp` (voir Lister les modèles d'e-mail).
`locale`	Étiquette de langue, par exemple `en` ou `de`.

En-têtes

En-tête	Description
`Idempotency-Key`	Facultatif, de 16 à 64 caractères parmi `A-Z a-z 0-9 _ -`. Répéter une requête avec la même clé renvoie le premier message et ne l'envoie ni ne le compte à nouveau. Les SDK et la CLI la définissent à votre place.

Requête

Champ	Type	Description
`to`	string	Obligatoire. Le destinataire : une adresse vérifiée d'un membre `active` du tableau de bord, sans nom d'affichage. La casse et les espaces en début ou fin sont ignorés.
`version`	integer	La version enregistrée à envoyer (1 ou plus). Par défaut : la version la plus récente.
`published`	boolean	`true` envoie la version publiée. Ne peut pas être combiné avec `version`.

Réponse

200 OK

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

Champ	Description
`message_id`	L'identifiant du message.
`state`	`queued` (il sera envoyé sous peu) ou `suppressed` (le destinataire figure sur la liste de suppression). Une requête répétée renvoie l'état actuel du premier message, qui peut aussi être `sent`, `failed` ou `expired`.
`version`	La version qui a été envoyée.
`accepted_at`	Date à laquelle le message a été accepté.

Erreurs

HTTP	code	Quand
400	`unknown_field`	Le corps contient un champ inconnu ou n'est pas un objet JSON.
400	`malformed_request`	Le corps n'est pas du JSON valide, ou `Idempotency-Key` est mal formé ou répété.
401	`unauthenticated`	L'identifiant est absent, invalide ou révoqué.
403	`insufficient_permissions`	L'identifiant ne dispose pas de l'autorisation requise.
403	`plan_feature_unavailable`	Le forfait de l'environnement n'inclut pas les modèles d'e-mail personnalisés (Startup et supérieurs ; `required_plan` indique lequel).
404	`not_found`	La famille ou la langue est inconnue, la version n'existe pas, ou `published` est défini et rien n'est publié.
409	`email_template_not_deliverable`	Le mode d'envoi ou l'état d'envoi de l'environnement n'autorise pas les modèles personnalisés.
422	`validation_failed`	`to` est absent ou n'est pas une adresse e-mail simple, `version` est inférieur à 1, `version` et `published` ont été envoyés tous les deux (`conflicts_with_published`), ou la version ne passe plus la validation.
422	`template_forbidden_construct`	La version utilise une construction Liquid en dehors du bac à sable.
422	`test_recipient_not_allowed`	Le destinataire n'est pas une adresse vérifiée d'un membre `active` du tableau de bord.
429	`rate_limited`	L'environnement a déjà envoyé 20 e-mails de test ce jour UTC, ou la limite de débit de l'API a été dépassée ; réessayez après la durée indiquée par `Retry-After`.
503	`test_recipient_source_unavailable`	Le destinataire ne peut pas être vérifié pour le moment ; rien n'a été envoyé. Réessayez après la durée indiquée par `Retry-After`.
503	`service_unavailable`	Une dépendance est temporairement indisponible ; réessayez après la durée indiquée par `Retry-After`.

Exemple

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

Données personnelles

Ce point de terminaison traite des données personnelles : utilisateurs du tableau de bord et contacts du compte. Données personnelles dans les API KeenAuth décrit ce qui est stocké, la durée de conservation et la manière dont elles sont supprimées. N'envoyez pas de catégories particulières de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.