# 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](preview.md) 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](list.md)). |
| `locale` | Locale-Tag, zum Beispiel `en` oder `de`. |

## Header

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

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

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

## Personenbezogene Daten

Dieser Endpunkt verarbeitet personenbezogene Daten: Dashboard-Benutzer und Kontaktpersonen des Kontos. [Personenbezogene Daten in den KeenAuth-APIs](/docs/policies/personal-data) 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).