Aller au contenu
Frontmail Docs

Présentation et concepts

Frontmail vous permet d’envoyer des e-mails directement depuis votre frontend – un formulaire de contact, une demande de réservation, une confirmation de commande – sans faire tourner votre propre backend. Vous connectez le fournisseur d’e-mail que vous utilisez déjà, vous concevez dans le tableau de bord un modèle HTML avec des paramètres typés, puis vous appelez une seule fonction :

import { init, send } from '@frontmail/browser';


init({ publicKey: 'pk_4f2a…' });
await send('svc_01J9…', 'tpl_01J9…', { name: 'Jana', message: 'Bonjour !' });

La requête arrive sur l’API Frontmail, qui la contrôle (origine, protection contre les bots, rate limits, validation des paramètres), réserve un crédit et place l’e-mail dans la file d’envoi. Un expéditeur génère ensuite le modèle et le délivre via votre fournisseur. Les événements de distribution (délivré, rejeté, ouvert…) remontent par les webhooks du fournisseur jusqu’à votre historique et vos statistiques.

Les briques de base

Section intitulée « Les briques de base »

Organisation

Section intitulée « Organisation »

Tout – clés, services, modèles, crédits, membres – appartient à une organisation. Un utilisateur peut être membre de plusieurs organisations et passer de l’une à l’autre. Chaque organisation a son forfait et son propre solde de crédits.

Clé publique et clé privée

Section intitulée « Clé publique et clé privée »
Clé publique pk_… Clé privée sk_…
Où elle se trouve Dans votre code frontend – ce n’est pas un secret Uniquement sur votre serveur – traitez-la comme un mot de passe
Comment elle est envoyée user_id dans le corps ou en-tête X-Frontmail-Public-Key Authorization: Bearer sk_… (ou accessToken dans le corps) – jamais depuis un navigateur : les requêtes avec un en-tête Origin sont refusées
Ce qui la protège Domaines autorisés, Turnstile, rate limits, protection contre les bots Sa confidentialité – elle contourne les contrôles d’origine et de CAPTCHA
Ce qu’elle permet send, send-form, envoi de fichiers, lecture du statut de ses propres messages Tout ce qui précède, plus send-batch, history, templates

Comme une clé publique est visible par toute personne qui ouvre votre page, Frontmail ne lui fait jamais confiance à elle seule. Lisez Clés publiques et privées avant la mise en production.

Services

Section intitulée « Services »

Un service est une connexion à un fournisseur d’e-mail : SMTP (Seznam, Zoho, votre propre serveur), Mailgun, Amazon SES, Postmark, Mailjet, Brevo, Resend, Gmail ou Outlook / Microsoft 365. Les identifiants sont chiffrés avec AWS KMS. Frontmail vérifie chaque service une fois par jour et immédiatement après une erreur d’authentification, et un modèle peut avoir un service de secours qui prend le relais quand le service principal tombe en panne. Voir Présentation des services.

Modèles

Section intitulée « Modèles »

Un modèle est un e-mail HTML complet (avec une version texte brut générée) plus l’objet, les destinataires (To, CC, BCC, Reply-To, From) et un schéma de paramètres. Les paramètres sont typés (string, email, number, date, list…) et validés à chaque envoi, et le corps utilise Handlebars pour les conditions, les boucles et les helpers de mise en forme. Voir Modèles HTML et Paramètres et types.

Crédits

Section intitulée « Crédits »

Un e-mail accepté = un crédit. Les crédits proviennent d’allocations (grants) :

  • subscription – le quota mensuel de votre forfait (non reportable),
  • pack – des packs de crédits prépayés valables 3 à 12 mois, disponibles sur tous les forfaits, Free compris,
  • bonus – des crédits ajoutés par le support Frontmail,
  • overdraft – un découvert de 10 % sur les forfaits payants, facturé sur votre prochaine facture.

Les crédits sont toujours prélevés sur l’allocation qui expire en premier, le découvert en dernier. Les envois de test depuis l’éditeur de modèle sont gratuits. Si un envoi échoue définitivement, le crédit est remboursé. Voir Ordre de consommation.

Aucun e-mail n’est abandonné en silence

Section intitulée « Aucun e-mail n’est abandonné en silence »

Quand vous n’avez plus de crédits, Frontmail ne jette pas votre e-mail. En mode hold (par défaut), il accepte la requête avec 202 { "status": "held" }, conserve le message et l’envoie automatiquement dès que des crédits sont de nouveau disponibles – après l’achat d’un pack, une recharge automatique, un passage à un forfait supérieur ou la période de facturation suivante. Lisez File d’attente des e-mails retenus.

Cycle de vie d’un message

Section intitulée « Cycle de vie d’un message »
accepted ─┬─► queued ─► sending ─► sent ─┬─► delivered
          │                              ├─► bounced
          │                              └─► complained
          ├─► held (no credits) ─► queued …   or ─► discarded (hold expired / manual)
          └─► (on provider auth error) held_service_error ─► queued … after the service is fixed
                                     failed (permanent error, credit refunded)

Tous les statuts sont expliqués dans Statuts des messages.

Étapes suivantes

Section intitulée « Étapes suivantes »