Présentation de l’API REST

Les SDK couvrent la plupart des besoins, mais tout ce qu’ils font n’est que du HTTPS + JSON que vous pouvez appeler depuis n’importe quel langage. La référence complète, générée, de chaque endpoint se trouve dans la référence de l’API REST.

URL de base

https://api.frontmail.dev

Tous les endpoints sont versionnés sous /v1. Les alias compatibles EmailJS POST /api/v1.0/email/send et POST /api/v1.0/email/send-form se comportent comme /v1/send et /v1/send-form.

Authentification

Clé	Envoyée comme	Endpoints autorisés
Clé publique pk_…	en-tête X-Frontmail-Public-Key: pk_…, ou user_id dans le corps	POST /v1/send, POST /v1/send-form, POST /v1/uploads, GET /v1/messages/:id avec l’en-tête X-Frontmail-Status-Token
Clé privée sk_…	en-tête Authorization: Bearer sk_…, ou accessToken dans le corps – uniquement depuis des serveurs (une requête avec un en-tête Origin reçoit 403 private_key_in_browser)	tous les endpoints

Les requêtes avec clé publique sans Origin ni Referer (serveurs, curl, applications natives) nécessitent Autoriser les applications mobiles ; sinon, elles reçoivent 403 origin_not_allowed.

GET /v1/health et GET /v1/public-config ne nécessitent aucune clé. Voir Clés publiques et privées pour le modèle de sécurité.

Endpoints

Méthode et chemin	Rôle
POST /v1/send	Envoyer un e-mail à partir d’un modèle (JSON)
POST /v1/send-form	Envoyer un e-mail à partir de multipart/form-data (les fichiers deviennent des pièces jointes)
POST /v1/send-batch	Envoyer jusqu’à 100 e-mails (clé privée)
POST /v1/uploads	Obtenir une URL présignée pour une pièce jointe volumineuse
GET /v1/messages/:id	Statut et événements d’un message
GET /v1/history	Historique des messages paginé (clé privée)
GET /v1/templates, GET /v1/templates/:id	Modèles avec leurs schémas de paramètres (clé privée)
GET /v1/public-config	Configuration publique, sans clé – la clé de site Turnstile mobile de Frontmail et l’URL de la page, utilisées par @frontmail/react-native (mise en cache possible pendant 1 heure)
GET /v1/health	Vérification de l’état du service

En-têtes

En-tête	Sens	Signification
Idempotency-Key	requête	Déduplique les nouvelles tentatives pendant 24 h (≤ 255 caractères) – voir Nouvelles tentatives et idempotence
X-Frontmail-Client	requête	Nom et version du SDK, p. ex. @frontmail/browser/0.3.1 (facultatif, aide le support)
X-Frontmail-Status-Token	requête	Le status_token de la réponse d’envoi, pour GET /v1/messages/:id avec une clé publique. L’ancien paramètre de requête ?token= fonctionne toujours mais finit dans les journaux d’accès – préférez l’en-tête
Retry-After	réponse	Secondes à attendre, avec 429

Exemple

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

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

status vaut queued ou held (plus de crédits en mode hold). Dans les deux cas, le message a été accepté – le code de réponse est 202.

Pour envoyer l’e-mail dans une langue du modèle, ajoutez "locale": "de" (n’importe quelle balise BCP 47) – dans /v1/send-form, utilisez le champ de formulaire fm_locale. La locale de la réponse est la langue réellement utilisée ; sans locale dans la requête, la langue par défaut est envoyée.

Erreurs

Toutes les erreurs ont la même forme :

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

Statuts possibles : 400, 401, 402 (uniquement en mode reject), 403, 404, 409, 413, 422, 429, 451, 5xx. Chaque code est expliqué dans Codes d’erreur.

Limites

• Paramètres : 256 ko de JSON par message ; chaînes de 50 000 caractères, sauf indication contraire du schéma.
• Lot : 100 messages par requête.
• Pièces jointes : selon le forfait, voir Forfaits.
• Requêtes par seconde : selon le forfait, voir Rate limits.