Test-E-Mail senden

POST /v1/email-templates/{family}/{locale}:test-send · Berechtigung email-templates:write · Startup-Tarif und höher

Rendert eine Version einer E-Mail-Vorlage mit denselben Beispieldaten wie preview und sendet sie über den normalen Zustellweg an eine Adresse, damit Sie sie in einem echten Posteingang prüfen können. Der Betreff beginnt mit [TEST] . Die Vorlage wird vor dem Versand erneut validiert.

Regeln:

Der Empfänger muss eine verifizierte E-Mail-Adresse eines active-Mitglieds Ihres Dashboard-Kontos sein. Jede andere Adresse wird abgelehnt, und die Adresse wird weder in der Antwort noch in Logs wiederholt.
Jede Umgebung kann höchstens 20 Test-E-Mails pro UTC-Tag senden. Die 21. wird mit 429 abgelehnt, bis zum nächsten UTC-Tag (Retry-After gibt die Wartezeit in Sekunden an).
Die Unterdrückungsliste gilt weiterhin. Ist der Empfänger unterdrückt, wird die Nachricht mit dem Status suppressed erfasst, nicht zugestellt und zählt trotzdem zum Tageslimit.
Die Umgebung muss benutzerdefinierte Vorlagen versenden dürfen: Ein Test-Versand wird abgelehnt, wenn der Zustellmodus platform_default ist oder das Senden eingeschränkt oder ausgesetzt ist.
Jeder angenommene Test-Versand wird als email_template.test_sent im Management-Auditprotokoll festgehalten, mit Familie, Locale und Version, aber ohne den Empfänger.

Pfadparameter

Parameter	Beschreibung
`family`	E-Mail-Familie, zum Beispiel `verify_email` oder `email_otp` (siehe E-Mail-Vorlagen auflisten).
`locale`	Locale-Tag, zum Beispiel `en` oder `de`.

Header	Beschreibung
`Idempotency-Key`	Optional, 16 bis 64 Zeichen aus `A-Z a-z 0-9 _ -`. Wiederholen Sie eine Anfrage mit demselben Schlüssel, wird die erste Nachricht zurückgegeben; sie wird nicht erneut gesendet oder gezählt. Die SDKs und die CLI setzen ihn für Sie.

Anfrage

Feld	Typ	Beschreibung
`to`	string	Erforderlich. Der Empfänger: eine verifizierte Adresse eines `active`-Dashboard-Mitglieds, ohne Anzeigenamen. Groß- und Kleinschreibung sowie umgebende Leerzeichen werden ignoriert.
`version`	integer	Die gespeicherte Version, die gesendet werden soll (1 oder höher). Standard: die neueste Version.
`published`	boolean	`true` sendet die veröffentlichte Version. Kann nicht zusammen mit `version` verwendet werden.

Antwort

200 OK

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

Feld	Beschreibung
`message_id`	Die Kennung der Nachricht.
`state`	`queued` (wird in Kürze gesendet) oder `suppressed` (der Empfänger steht auf der Unterdrückungsliste). Eine wiederholte Anfrage liefert den aktuellen Status der ersten Nachricht, der auch `sent`, `failed` oder `expired` sein kann.
`version`	Die gesendete Version.
`accepted_at`	Zeitpunkt, zu dem die Nachricht angenommen wurde.

Fehler

HTTP	Code	Wann
400	`unknown_field`	Der Body enthält ein unbekanntes Feld oder ist kein JSON-Objekt.
400	`malformed_request`	Der Body ist kein gültiges JSON, oder `Idempotency-Key` ist fehlerhaft oder doppelt angegeben.
401	`unauthenticated`	Die Anmeldeinformation fehlt, ist ungültig oder wurde widerrufen.
403	`insufficient_permissions`	Die Anmeldeinformation besitzt nicht die erforderliche Berechtigung.
403	`plan_feature_unavailable`	Der Tarif der Umgebung umfasst keine benutzerdefinierten E-Mail-Vorlagen (Startup und höher; `required_plan` gibt den Tarif an).
404	`not_found`	Die Familie oder Locale ist unbekannt, die Version existiert nicht, oder `published` ist gesetzt und nichts ist veröffentlicht.
409	`email_template_not_deliverable`	Der Zustellmodus oder der Sendestatus der Umgebung erlaubt keine benutzerdefinierten Vorlagen.
422	`validation_failed`	`to` fehlt oder ist keine einfache E-Mail-Adresse, `version` ist kleiner als 1, beide Felder `version` und `published` wurden gesendet (`conflicts_with_published`), oder die Version besteht die Validierung nicht mehr.
422	`template_forbidden_construct`	Die Version verwendet ein Liquid-Konstrukt außerhalb der Sandbox.
422	`test_recipient_not_allowed`	Der Empfänger ist keine verifizierte Adresse eines `active`-Dashboard-Mitglieds.
429	`rate_limited`	Die Umgebung hat an diesem UTC-Tag bereits 20 Test-E-Mails gesendet, oder das API-Ratenlimit wurde überschritten; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`.
503	`test_recipient_source_unavailable`	Der Empfänger kann im Moment nicht geprüft werden; es wurde nichts gesendet. Wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`.
503	`service_unavailable`	Eine Abhängigkeit ist vorübergehend nicht verfügbar; wiederholen Sie die Anfrage nach dem Zeitraum aus `Retry-After`.

Beispiel

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

Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Dashboard-Benutzer und Kontaktpersonen des Kontos. Personenbezogene Daten in den KeenAuth-APIs beschreibt, welche Daten gespeichert werden, wie lange sie aufbewahrt werden und wie sie gelöscht werden. Senden Sie in keinem Feld besondere Kategorien personenbezogener Daten (Gesundheit, biometrische Daten, Religion, politische Meinungen, sexuelle Orientierung).