Prehľad REST API

SDK pokryjú väčšinu potrieb, ale všetko, čo robia, je obyčajné HTTPS + JSON, ktoré môžete volať z ľubovoľného jazyka. Kompletná generovaná referencia všetkých endpointov je v referencii REST API.

Základná URL

https://api.frontmail.dev

Všetky endpointy sú verzované pod /v1. Aliasy kompatibilné s EmailJS POST /api/v1.0/email/send a POST /api/v1.0/email/send-form sa správajú rovnako ako /v1/send a /v1/send-form.

Autentifikácia

Kľúč	Ako ho poslať	Povolené endpointy
Verejný kľúč `pk_…`	Hlavička `X-Frontmail-Public-Key: pk_…` alebo `user_id` v tele požiadavky	`POST /v1/send`, `POST /v1/send-form`, `POST /v1/uploads`, `GET /v1/messages/:id` s hlavičkou `X-Frontmail-Status-Token`
Súkromný kľúč `sk_…`	Hlavička `Authorization: Bearer sk_…` alebo `accessToken` v tele požiadavky – len zo servera (požiadavka s hlavičkou `Origin` dostane `403 private_key_in_browser`)	všetky endpointy

Požiadavky s verejným kľúčom bez Origin aj Referer (servery, curl, natívne aplikácie) potrebujú Povoliť mobilné aplikácie; inak dostanú 403 origin_not_allowed.

GET /v1/health a GET /v1/public-config žiadny kľúč nepotrebujú. Bezpečnostný model opisuje stránka Verejný a súkromný kľúč.

Endpointy

Metóda a cesta	Účel
`POST /v1/send`	Odošle jeden e-mail podľa šablóny (JSON)
`POST /v1/send-form`	Odošle jeden e-mail z `multipart/form-data` (zo súborov sa stanú prílohy)
`POST /v1/send-batch`	Odošle až 100 e-mailov (súkromný kľúč)
`POST /v1/uploads`	Vráti predpodpísanú (presigned) URL pre veľkú prílohu
`GET /v1/messages/:id`	Stav a udalosti správy
`GET /v1/history`	Stránkovaná história správ (súkromný kľúč)
`GET /v1/templates`, `GET /v1/templates/:id`	Šablóny so schémami parametrov (súkromný kľúč)
`GET /v1/public-config`	Verejná konfigurácia bez kľúča – mobilný site key Turnstile Frontmailu a adresa stránky widgetu; používa ju `@frontmail/react-native` (možno cachovať 1 hodinu)
`GET /v1/health`	Health check

Hlavičky

Hlavička	Smer	Význam
`Idempotency-Key`	požiadavka	Deduplikuje opakované pokusy počas 24 h (≤ 255 znakov) – pozrite Opakovanie a idempotencia
`X-Frontmail-Client`	požiadavka	Názov a verzia SDK, napr. `@frontmail/browser/0.3.1` (voliteľné, uľahčí podporu)
`X-Frontmail-Status-Token`	požiadavka	`status_token` z odpovede na odoslanie, pre `GET /v1/messages/:id` s verejným kľúčom. Starší parameter `?token=` stále funguje, ale končí v prístupových logoch – uprednostnite hlavičku
`Retry-After`	odpoveď	Počet sekúnd, ktoré treba počkať, pri `429`

Prí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_…", "locale": "en" }

status je queued alebo held (došli kredity a organizácia je v režime hold). Oboje znamená, že správa bola prijatá – kód odpovede je 202.

Ak chcete e-mail poslať v niektorom jazyku šablóny, pridajte "locale": "de" (akúkoľvek značku BCP 47) – v /v1/send-form použite pole formulára fm_locale. locale v odpovedi je skutočne použitý jazyk; bez locale v požiadavke sa pošle predvolený jazyk.

Chyby

Všetky chyby majú rovnaký 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 (len v režime reject), 403, 404, 409, 413, 422, 429, 451, 5xx. Každý kód vysvetľuje stránka Kódy chýb.

Limity

Parametre: 256 kB JSON-u na správu; reťazce 50 000 znakov, ak schéma neurčuje inak.
Batch: 100 správ na požiadavku.
Prílohy: podľa tarifu, pozrite Tarify.
Požiadavky za sekundu: podľa tarifu, pozrite Rate limity.