Panoramica dell’API REST

Gli SDK coprono la maggior parte delle esigenze, ma tutto ciò che fanno è semplice HTTPS + JSON che puoi chiamare da qualsiasi linguaggio. La reference completa e generata di ogni endpoint si trova nella reference dell’API REST.

URL di base

https://api.frontmail.dev

Tutti gli endpoint sono versionati sotto /v1. Gli alias compatibili con EmailJS POST /api/v1.0/email/send e POST /api/v1.0/email/send-form si comportano come /v1/send e /v1/send-form.

Autenticazione

Chiave	Come inviarla	Endpoint consentiti
Chiave pubblica pk_…	Header X-Frontmail-Public-Key: pk_…, oppure user_id nel body	POST /v1/send, POST /v1/send-form, POST /v1/uploads, GET /v1/messages/:id con l’header X-Frontmail-Status-Token
Chiave privata sk_…	Header Authorization: Bearer sk_…, oppure accessToken nel body – solo dai server (una richiesta con l’header Origin riceve 403 private_key_in_browser)	tutti gli endpoint

Le richieste con chiave pubblica senza Origin e Referer (server, curl, app native) richiedono Consenti app mobile; altrimenti ricevono 403 origin_not_allowed.

GET /v1/health e GET /v1/public-config non richiedono alcuna chiave. Il modello di sicurezza è descritto in Chiavi pubbliche e private.

Endpoint

Metodo e percorso	Scopo
POST /v1/send	Invia un’email da un modello (JSON)
POST /v1/send-form	Invia un’email da multipart/form-data (i file diventano allegati)
POST /v1/send-batch	Invia fino a 100 email (chiave privata)
POST /v1/uploads	Ottiene un URL prefirmato per un allegato di grandi dimensioni
GET /v1/messages/:id	Stato ed eventi di un messaggio
GET /v1/history	Cronologia dei messaggi paginata (chiave privata)
GET /v1/templates, GET /v1/templates/:id	Modelli con i relativi schemi dei parametri (chiave privata)
GET /v1/public-config	Configurazione pubblica, senza chiave – la site key Turnstile mobile di Frontmail e l’URL della pagina, usati da @frontmail/react-native (memorizzabile in cache per 1 ora)
GET /v1/health	Controllo dello stato del servizio

Header

Header	Direzione	Significato
Idempotency-Key	richiesta	Deduplica i tentativi ripetuti per 24 h (≤ 255 caratteri) – vedi Tentativi e idempotenza
X-Frontmail-Client	richiesta	Nome e versione dell’SDK, ad es. @frontmail/browser/0.3.1 (facoltativo, aiuta il supporto)
X-Frontmail-Status-Token	richiesta	Il status_token della risposta all’invio, per GET /v1/messages/:id con chiave pubblica. Il vecchio parametro di query ?token= funziona ancora, ma finisce nei log di accesso – preferisci l’header
Retry-After	risposta	Secondi da attendere, con 429

Esempio

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": "Giulia", "email": "giulia@example.com", "message": "Ciao!" },
    "turnstile_token": "0.AbCd…"
  }'

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

status è queued oppure held (crediti esauriti in modalità hold). Entrambi significano che il messaggio è stato accettato – il codice di risposta è 202.

Per inviare l’email in una lingua del modello, aggiungi "locale": "de" (qualsiasi tag BCP 47) – in /v1/send-form usa il campo del modulo fm_locale. Il locale della risposta è la lingua usata davvero; senza locale nella richiesta viene inviata la lingua predefinita.

Errori

Tutti gli errori hanno la stessa forma:

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

Stati possibili: 400, 401, 402 (solo in modalità reject), 403, 404, 409, 413, 422, 429, 451, 5xx. Ogni codice è spiegato in Codici di errore.

Limiti

• Parametri: 256 kB di JSON per messaggio; stringhe da 50.000 caratteri, salvo diversa indicazione dello schema.
• Batch: 100 messaggi per richiesta.
• Allegati: in base al piano, vedi Piani.
• Richieste al secondo: in base al piano, vedi Rate limit.