REST-API im Überblick

Die SDKs decken die meisten Anwendungsfälle ab, aber alles, was sie tun, ist schlichtes HTTPS + JSON, das Sie aus jeder Sprache aufrufen können. Die vollständige, generierte Referenz aller Endpunkte finden Sie in der REST-API-Referenz.

Basis-URL

https://api.frontmail.dev

Alle Endpunkte sind unter /v1 versioniert. Die EmailJS-kompatiblen Aliase POST /api/v1.0/email/send und POST /api/v1.0/email/send-form verhalten sich wie /v1/send und /v1/send-form.

Authentifizierung

Schlüssel	Übergabe	Erlaubte Endpunkte
Öffentlicher Schlüssel pk_…	Header X-Frontmail-Public-Key: pk_… oder user_id im Body	POST /v1/send, POST /v1/send-form, POST /v1/uploads, GET /v1/messages/:id mit dem Header X-Frontmail-Status-Token
Privater Schlüssel sk_…	Header Authorization: Bearer sk_… oder accessToken im Body – nur von Servern (eine Anfrage mit Origin-Header erhält 403 private_key_in_browser)	alle Endpunkte

Anfragen mit öffentlichem Schlüssel ohne Origin und Referer (Server, curl, native Apps) benötigen Mobile Apps erlauben, sonst erhalten sie 403 origin_not_allowed.

GET /v1/health und GET /v1/public-config brauchen keinen Schlüssel. Das Sicherheitsmodell beschreibt Öffentliche und private Schlüssel.

Endpunkte

Methode & Pfad	Zweck
POST /v1/send	Eine E-Mail aus einer Vorlage senden (JSON)
POST /v1/send-form	Eine E-Mail aus multipart/form-data senden (Dateien werden zu Anhängen)
POST /v1/send-batch	Bis zu 100 E-Mails senden (privater Schlüssel)
POST /v1/uploads	Eine vorsignierte URL für einen großen Anhang abrufen
GET /v1/messages/:id	Status und Ereignisse einer Nachricht
GET /v1/history	Nachrichtenverlauf mit Paginierung (privater Schlüssel)
GET /v1/templates, GET /v1/templates/:id	Vorlagen mit Parameterschemas (privater Schlüssel)
GET /v1/public-config	Öffentliche Konfiguration ohne Schlüssel – der mobile Turnstile-Site-Key von Frontmail und die Seiten-URL, genutzt von @frontmail/react-native (1 Stunde cachebar)
GET /v1/health	Health-Check

Header

Header	Richtung	Bedeutung
Idempotency-Key	Anfrage	Dedupliziert Wiederholungen 24 Std. lang (≤ 255 Zeichen) – siehe Wiederholungen und Idempotenz
X-Frontmail-Client	Anfrage	Name und Version des SDK, z. B. @frontmail/browser/0.3.1 (optional, hilft dem Support)
X-Frontmail-Status-Token	Anfrage	status_token aus der Sendeantwort, für GET /v1/messages/:id mit öffentlichem Schlüssel. Der ältere Query-Parameter ?token= funktioniert weiterhin, landet aber in Zugriffslogs – nutzen Sie lieber den Header
Retry-After	Antwort	Wartezeit in Sekunden bei 429

Beispiel

curl https://api.frontmail.dev/v1/send \
  -H 'Content-Type: application/json' \
  -H 'X-Frontmail-Public-Key: pk_4f2a…' \
  -H 'Origin: https://example.com' \
  -H 'Idempotency-Key: 5f0c6f8e-1d2a-4c55-9f6b-2d7c1f4a9e10' \
  -d '{
    "service_id": "svc_01J9…",
    "template_id": "tpl_01J9…",
    "template_params": { "name": "Jana", "email": "jana@example.com", "message": "Hallo!" },
    "turnstile_token": "0.AbCd…"
  }'

{ "message_id": "msg_01J9Z3K7Q2", "status": "queued", "status_token": "st_…", "locale": "en" }

status ist queued oder held (keine Credits mehr im Modus hold). Beides bedeutet, dass die Nachricht angenommen wurde – der Antwortcode ist 202.

Um die E-Mail in einer Sprache der Vorlage zu versenden, fügen Sie "locale": "de" hinzu (ein beliebiges BCP-47-Tag) – in /v1/send-form verwenden Sie das Formularfeld fm_locale. Das Feld locale der Antwort ist die tatsächlich verwendete Sprache; ohne locale in der Anfrage wird die Standardsprache versendet.

Fehler

Alle Fehler haben dieselbe Form:

{ "error": { "code": "origin_not_allowed", "message": "…", "docs_url": "https://docs.frontmail.dev/reference/errors/#origin-not-allowed", "details": {} } }

Mögliche Status: 400, 401, 402 (nur im Modus reject), 403, 404, 409, 413, 422, 429, 451, 5xx. Jeder Code ist unter Fehlercodes erklärt.

Limits

• Parameter: 256 kB JSON pro Nachricht; Strings 50.000 Zeichen, sofern das Schema nichts anderes vorgibt.
• Batch: 100 Nachrichten pro Anfrage.
• Anhänge: je nach Tarif, siehe Tarife.
• Anfragen pro Sekunde: je nach Tarif, siehe Rate Limits.