Mailgun

Mailgun est un service d’e-mails transactionnels pensé pour les développeurs. C’est un choix par défaut solide pour Frontmail : une API simple, des régions États-Unis et UE, des données d’événements détaillées et des webhooks pour la livraison, les rebonds, les plaintes, les ouvertures et les clics.

Choisissez Mailgun si vous envoyez des e-mails transactionnels (inscriptions, reçus, notifications, envois de formulaires) depuis votre propre domaine, voulez suivre les rebonds et les plaintes, et préférez garder vos données dans l’UE (région UE de Mailgun). Pour quelques e-mails depuis une boîte personnelle, SMTP ou Gmail est plus simple. Consultez la présentation des services d’envoi pour une comparaison.

Prérequis

Un compte Mailgun. Les nouveaux comptes démarrent avec un domaine sandbox qui ne peut envoyer qu’à des destinataires autorisés (voir Sandbox et limites).
Un domaine d’envoi ajouté et vérifié dans Mailgun – nous recommandons un sous-domaine comme mg.example.com, afin de séparer la réputation et le DNS de votre domaine racine.
Une clé API. Créez une clé dédiée à Frontmail dans Account settings → API security → Add new key (ancienne interface : Account → API keys).
- Utilisez une clé avec le rôle le plus restrictif qui permet encore d’envoyer et de lire les informations du domaine (p. ex. Developer plutôt qu’Admin).
- Une clé d’envoi de domaine (Sending → Domain settings → Sending API keys) peut envoyer, mais ne peut pas lire le domaine : Tester la connexion et la vérification d’état quotidienne la signaleront donc comme défaillante. Utilisez une clé de compte privée.
Facultatif : la HTTP webhook signing key de Sending → Webhooks pour les événements de livraison.

Connexion dans Frontmail

Ouvrez Services d’envoi → Ajouter un service → Mailgun.
Remplissez les champs :

Champ	Où le trouver	Exemple
Région	La région affichée à côté du domaine dans Mailgun (Sending → Domains)	`UE (api.eu.mailgun.net)`
Domaine d’envoi	Sending → Domains, exactement tel qu’indiqué	`mg.example.com`
Clé API	Account settings → API security (affichée une seule fois à la création)	`key-3ax6…` / `a1b2c3…-us`
Clé de signature des webhooks	Sending → Webhooks → HTTP webhook signing key	`8c1f…`
E-mails par seconde (max.)	Facultatif ; 10/s par défaut	`5`

Cliquez sur Vérifier et enregistrer – Frontmail interroge l’API Mailgun pour le domaine et vérifie que la clé, la région et le domaine correspondent.
Le service est enregistré une fois la vérification réussie. Les identifiants sont chiffrés avec le chiffrement d’enveloppe d’AWS KMS ; seul le processus d’envoi les déchiffre, au moment de l’envoi.

L’adresse From du modèle doit appartenir au domaine d’envoi (p. ex. hello@mg.example.com) – ou au domaine racine si c’est celui-ci que vous avez vérifié.

DNS : SPF, DKIM et DMARC

Mailgun affiche les enregistrements exacts de votre domaine sous Sending → Domains → DNS records. Pour mg.example.com, ils ressemblent à ceci :

; SPF
mg.example.com.                     TXT    "v=spf1 include:mailgun.org ~all"

; DKIM – le sélecteur est généré pour chaque domaine (p. ex. pic, k1, smtp, mx)
pic._domainkey.mg.example.com.      TXT    "k=rsa; p=MIGfMA0GCSqGSIb3DQEB…"

; Réception / gestion des rebonds (recommandé)
mg.example.com.                     MX 10  mxa.mailgun.org.
mg.example.com.                     MX 10  mxb.mailgun.org.     ; UE : mxa.eu.mailgun.org / mxb.eu.mailgun.org

; Suivi des ouvertures et des clics
email.mg.example.com.               CNAME  mailgun.org.         ; UE : eu.mailgun.org

; DMARC – sur le domaine organisationnel, commencez par la surveillance
_dmarc.example.com.                 TXT    "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Copiez le sélecteur DKIM depuis Mailgun, pas depuis cet exemple – il diffère selon le domaine (pic._domainkey, k1._domainkey, …). Les domaines plus récents peuvent aussi utiliser un DKIM délégué via CNAME avec rotation automatique des clés.
Si le domaine racine a déjà un enregistrement SPF pour votre boîte aux lettres, aucun problème – le sous-domaine a son propre enregistrement SPF.
Cliquez sur Verify DNS settings dans Mailgun ; la propagation peut prendre de quelques minutes à quelques heures.
Une fois que les rapports DMARC sont propres, durcissez en p=quarantine, puis plus tard en p=reject.

Régions

Mailgun exploite deux régions totalement séparées :

Région	Hôte de l’API	À utiliser quand
États-Unis	`api.mailgun.net`	le domaine a été créé dans la région États-Unis (par défaut)
UE	`api.eu.mailgun.net`	le domaine a été créé dans la région UE (les données restent dans l’UE)

Un domaine n’existe que dans une seule région : choisissez donc la région dans laquelle le domaine a été créé. Une incohérence renvoie 404 Domain not found, que Frontmail traite comme une erreur d’authentification. La région ne peut pas être modifiée ensuite – pour changer, ajoutez de nouveau le domaine dans l’autre région.

Sandbox et limites

Domaine sandbox (sandbox123….mailgun.org) : envoie uniquement à des destinataires autorisés (5 au maximum) qui ont confirmé un e-mail d’invitation. Tout le reste échoue avec « Free accounts are for test purposes only ». Bien pour un premier test, pas pour la production.
Offre gratuite : environ 100 e-mails par jour.
Les nouveaux comptes / domaines peuvent être limités par Mailgun tant que vous n’avez pas d’historique d’envoi ou que vous n’avez pas terminé la vérification de votre entreprise.
Le débit par défaut de Frontmail pour Mailgun est de 10 messages par seconde et par service ; baissez-le dans E-mails par seconde (max.) si Mailgun vous limite.

Webhooks (suivi de livraison)

Mailgun peut indiquer ce qui s’est passé après avoir accepté un message.

Copiez l’URL du webhook depuis la page du service dans Frontmail (bouton de copie à côté de URL du webhook). Elle ressemble à ceci :
```
https://api.frontmail.dev/webhooks/providers/mailgun/<token>
```
<token> est propre à ce service – ne le partagez pas entre plusieurs services.
Dans Mailgun, ouvrez Sending → Webhooks, choisissez le bon domaine (et la bonne région), puis ajoutez l’URL pour ces événements :

Événement Mailgun	Événement Frontmail
Delivered	`delivered`
Permanent failure	`bounced` – l’adresse est ajoutée à la liste de suppression
Temporary failure	enregistré sur le message ; Mailgun continue de réessayer
Spam complaints	`complained` – ajoutée à la liste de suppression
Opens	`opened` (nécessite le suivi des ouvertures sur le domaine)
Clicks	`clicked` (nécessite le suivi des clics sur le domaine)

Copiez la HTTP webhook signing key de la même page dans le champ Clé de signature des webhooks du service dans Frontmail.

Vérification de la signature : chaque webhook Mailgun contient timestamp, token et signature. Frontmail calcule le HMAC-SHA256 de timestamp + token avec votre clé de signature et refuse les requêtes dont la signature ne correspond pas. Sans clé de signature, les événements ne peuvent pas être vérifiés et sont ignorés.

Frontmail marque chaque message avec v:frontmail_message_id, afin que les événements soient associés au bon message même lorsque vous envoyez le même modèle de nombreuses fois.

Erreurs courantes

Frontmail classe les erreurs du fournisseur en trois catégories :

auth – le service est cassé (clé API invalide, 401/403, mauvais domaine ou mauvaise région, restrictions du sandbox). Le service est marqué unhealthy et le propriétaire reçoit un e-mail ainsi qu’une bannière dans le tableau de bord. Si le modèle a un service de secours, le message part par celui-ci ; sinon le crédit est remboursé et le message attend dans la file d’attente des e-mails retenus en held_service_error, pour partir automatiquement une fois le service réparé (revérifié à l’enregistrement et lors de la vérification d’état quotidienne).
permanent – ce message ne peut pas être envoyé (destinataire invalide, erreur de validation 4xx). Le service de secours est essayé s’il est configuré ; sinon le statut est failed et le crédit est remboursé.
transient – délais dépassés, 5xx, limitation 429. Relancé avec un délai exponentiel ; une fois les tentatives épuisées, le message passe en failed et le crédit est remboursé.

Réponse de Mailgun	Catégorie	Que faire
`401 Forbidden`	auth	La clé API est erronée, supprimée ou appartient à un autre compte. Créez une nouvelle clé et mettez à jour le service.
`404 Domain not found: mg.example.com`	auth	Vérifiez l’orthographe du domaine et la Région (les domaines UE nécessitent `api.eu.mailgun.net`).
`400 Domain mg.example.com is not allowed to send: Free accounts are for test purposes only…`	auth	Domaine sandbox ou compte non vérifié – ajoutez un destinataire autorisé, vérifiez votre propre domaine ou passez à une offre supérieure.
`403` « account disabled / domain disabled »	auth	Mailgun a suspendu l’envoi ; consultez le tableau de bord Mailgun et contactez leur support.
`400 'to' parameter is not a valid address`	permanent	L’adresse du destinataire est mal formée – voir destinataire invalide.
`413 Request Entity Too Large`	permanent	Le message et ses pièces jointes dépassent la taille maximale de Mailgun (25 Mo).
`429 Too Many Requests`	transient	Limitation ; Frontmail respecte `Retry-After`. Baissez E-mails par seconde (max.) si cela arrive souvent.
`500` / `502` / `503`, délai dépassé	transient	Panne chez Mailgun – rien à faire, Frontmail relance.

Liste de contrôle

Domaine d’envoi propre (p. ex. mg.example.com) ajouté et vérifié dans Mailgun
SPF, DKIM, MX et CNAME de suivi publiés ; DMARC au moins en p=none
La Région dans Frontmail correspond à la région du domaine
Clé API privée avec un rôle restreint, pas une clé d’envoi de domaine
Tester la connexion réussit
URL du webhook ajoutée pour delivered, permanent failure, complaints (+ opens/clicks si nécessaire)
Clé de signature des webhooks copiée dans Frontmail
Adresse d’expéditeur du modèle sur le domaine vérifié