Přehled REST API

SDK pokryjí většinu potřeb, ale všechno, co dělají, je obyčejné HTTPS + JSON, které můžete volat z libovolného jazyka. Kompletní generovaná reference všech endpointů je v referenci REST API.

Základní URL

https://api.frontmail.dev

Všechny endpointy jsou verzované pod /v1. Aliasy kompatibilní s EmailJS POST /api/v1.0/email/send a POST /api/v1.0/email/send-form se chovají stejně jako /v1/send a /v1/send-form.

Autentizace

Klíč	Jak ho poslat	Povolené endpointy
Public key pk_…	Hlavička X-Frontmail-Public-Key: pk_…, nebo user_id v těle požadavku	POST /v1/send, POST /v1/send-form, POST /v1/uploads, GET /v1/messages/:id s hlavičkou X-Frontmail-Status-Token
Private key sk_…	Hlavička Authorization: Bearer sk_…, nebo accessToken v těle požadavku – jen ze serveru (požadavek s hlavičkou Origin dostane 403 private_key_in_browser)	všechny endpointy

Požadavky s public key bez Origin i Referer (servery, curl, nativní aplikace) potřebují Povolit mobilní aplikace; jinak dostanou 403 origin_not_allowed.

GET /v1/health a GET /v1/public-config žádný klíč nepotřebují. Bezpečnostní model popisuje stránka Public key a private key.

Endpointy

Metoda a cesta	Účel
POST /v1/send	Odešle jeden e-mail podle šablony (JSON)
POST /v1/send-form	Odešle jeden e-mail z multipart/form-data (soubory se stanou přílohami)
POST /v1/send-batch	Odešle až 100 e-mailů (private key)
POST /v1/uploads	Vrátí presigned URL pro velkou přílohu
GET /v1/messages/:id	Stav a události zprávy
GET /v1/history	Stránkovaná historie zpráv (private key)
GET /v1/templates, GET /v1/templates/:id	Šablony se schématy parametrů (private key)
GET /v1/public-config	Veřejná konfigurace bez klíče – mobilní site key Turnstile Frontmailu a adresa stránky widgetu; používá ji @frontmail/react-native (lze cachovat 1 hodinu)
GET /v1/health	Health-check

Hlavičky

Hlavička	Směr	Význam
Idempotency-Key	požadavek	Deduplikuje opakované pokusy po dobu 24 h (≤ 255 znaků) – viz Opakování a idempotence
X-Frontmail-Client	požadavek	Název a verze SDK, např. @frontmail/browser/0.3.1 (volitelné, usnadní podporu)
X-Frontmail-Status-Token	požadavek	status_token z odpovědi na odeslání, pro GET /v1/messages/:id s public key. Starší parametr ?token= pořád funguje, ale končí v přístupových lozích – dávejte přednost hlavičce
Retry-After	odpověď	Počet sekund, které je třeba počkat, při 429

Příklad

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": "Hi!" },
    "turnstile_token": "0.AbCd…"
  }'

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

status je queued, nebo held (došly kredity a organizace je v režimu hold). Obojí znamená, že zpráva byla přijata – kód odpovědi je 202.

Chyby

Všechny chyby mají stejný tvar:

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

Možné stavové kódy: 400, 401, 402 (jen v režimu reject), 403, 404, 409, 413, 422, 429, 451, 5xx. Každý kód vysvětluje stránka Kódy chyb.

Limity

• Parametry: 256 kB JSONu na zprávu; řetězce 50 000 znaků, pokud schéma neurčuje jinak.
• Batch: 100 zpráv na požadavek.
• Přílohy: podle tarifu, viz Tarify.
• Požadavky za sekundu: podle tarifu, viz Rate limity.