Przegląd REST API

SDK pokrywają większość potrzeb, ale wszystko, co robią, to zwykłe HTTPS + JSON, które wywołasz z dowolnego języka. Pełna, generowana dokumentacja wszystkich endpointów jest w referencji REST API.

Bazowy URL

https://api.frontmail.dev

Wszystkie endpointy są wersjonowane pod /v1. Aliasy zgodne z EmailJS POST /api/v1.0/email/send i POST /api/v1.0/email/send-form działają tak samo jak /v1/send i /v1/send-form.

Uwierzytelnianie

Klucz	Jak go wysłać	Dozwolone endpointy
Klucz publiczny `pk_…`	Nagłówek `X-Frontmail-Public-Key: pk_…` albo `user_id` w treści żądania	`POST /v1/send`, `POST /v1/send-form`, `POST /v1/uploads`, `GET /v1/messages/:id` z nagłówkiem `X-Frontmail-Status-Token`
Klucz prywatny `sk_…`	Nagłówek `Authorization: Bearer sk_…` albo `accessToken` w treści żądania – tylko z serwera (żądanie z nagłówkiem `Origin` dostaje `403 private_key_in_browser`)	wszystkie endpointy

Żądania z kluczem publicznym bez Origin i Referer (serwery, curl, aplikacje natywne) wymagają opcji Zezwól na aplikacje mobilne; w przeciwnym razie dostają 403 origin_not_allowed.

GET /v1/health i GET /v1/public-config nie wymagają klucza. Model bezpieczeństwa opisuje strona Klucze publiczne i prywatne.

Endpointy

Metoda i ścieżka	Do czego służy
`POST /v1/send`	Wysyła jeden e-mail z szablonu (JSON)
`POST /v1/send-form`	Wysyła jeden e-mail z `multipart/form-data` (pliki stają się załącznikami)
`POST /v1/send-batch`	Wysyła do 100 e-maili (klucz prywatny)
`POST /v1/uploads`	Zwraca presigned URL dla dużego załącznika
`GET /v1/messages/:id`	Status i zdarzenia wiadomości
`GET /v1/history`	Stronicowana historia wiadomości (klucz prywatny)
`GET /v1/templates`, `GET /v1/templates/:id`	Szablony ze schematami parametrów (klucz prywatny)
`GET /v1/public-config`	Publiczna konfiguracja bez klucza – mobilny site key Turnstile Frontmail i adres strony widgetu; korzysta z niej `@frontmail/react-native` (można cache’ować przez 1 godzinę)
`GET /v1/health`	Health check

Nagłówki

Nagłówek	Kierunek	Znaczenie
`Idempotency-Key`	żądanie	Deduplikuje ponowne próby przez 24 h (≤ 255 znaków) – zobacz Ponawianie i idempotencja
`X-Frontmail-Client`	żądanie	Nazwa i wersja SDK, np. `@frontmail/browser/0.3.1` (opcjonalny, ułatwia pracę supportowi)
`X-Frontmail-Status-Token`	żądanie	`status_token` z odpowiedzi na wysyłkę, dla `GET /v1/messages/:id` z kluczem publicznym. Starszy parametr `?token=` nadal działa, ale trafia do logów dostępu – lepiej używać nagłówka
`Retry-After`	odpowiedź	Liczba sekund, które trzeba odczekać, przy `429`

Przykład

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

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

status to queued albo held (skończyły się kredyty, a organizacja jest w trybie hold). Oba oznaczają, że wiadomość została przyjęta – kod odpowiedzi to 202.

Żeby wysłać e-mail w jednym z języków szablonu, dodaj "locale": "de" (dowolny znacznik BCP 47) – w /v1/send-form użyj pola formularza fm_locale. locale w odpowiedzi to język faktycznie użyty; bez locale w żądaniu wysyłany jest język domyślny.

Błędy

Wszystkie błędy mają ten sam kształt:

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

Możliwe statusy: 400, 401, 402 (tylko w trybie reject), 403, 404, 409, 413, 422, 429, 451, 5xx. Każdy kod wyjaśnia strona Kody błędów.

Limity

Parametry: 256 kB JSON-a na wiadomość; ciągi znaków do 50 000 znaków, jeśli schemat nie mówi inaczej.
Batch: 100 wiadomości na żądanie.
Załączniki: zależnie od planu, zobacz Plany.
Żądania na sekundę: zależnie od planu, zobacz Rate limity.