Aller au contenu principal

Mailgun : Guide technique complet pour l'email transactionnel

Par CaptainDNS
Publié le 21 janvier 2026

Dashboard Mailgun avec configuration Domain Authentication et API REST
TL;DR
  • 📢 Mailgun utilise votre domaine dans le Return-Path (bounce+id@votredomaine.com), permettant l'alignement SPF natif pour DMARC dès le plan de base.
  • L'API REST est la méthode recommandée : jusqu'à 1 000 destinataires par appel, rate limits non documentés (sauf Domains API : 300 req/min).
  • Automatic Sender Security génère 2 CNAME DKIM avec rotation automatique tous les 120 jours, clés 2048 bits par défaut.
  • IP dédiée recommandée à partir de 1 million emails/mois, avec warm-up automatique sur 15+ jours et coût de 59$/IP/mois supplémentaire.
  • Plan Flex augmenté à 2,00$/1000 emails depuis décembre 2025 (doublement du tarif).

Introduction

Mailgun s'est imposé comme l'une des plateformes d'email transactionnel les plus robustes du marché, traitant plus de 600 milliards d'emails par an pour plus de 100 000 clients. Acquis par Sinch en décembre 2021 pour 1,9 milliard USD, le service combine une API REST puissante, un relay SMTP universel et des fonctionnalités d'authentification avancées qui le distinguent de la concurrence.

La force de Mailgun réside dans trois piliers techniques majeurs : une approche API-first orientée développeurs, une Domain Verification qui utilise votre propre domaine pour le Return-Path (alignement SPF natif pour DMARC), et un système de rotation automatique des clés DKIM 2048 bits tous les 120 jours sans interruption de service.

Ce guide s'adresse aux développeurs, DevOps, et architectes système qui cherchent à intégrer Mailgun pour l'email transactionnel avec une compréhension complète de l'infrastructure : configuration DNS, choix API vs SMTP, gestion des IP dédiées, limites techniques, et webhooks d'événements.

API REST vs SMTP Relay : architecture et choix d'intégration

Mailgun propose deux méthodes d'intégration pour l'email transactionnel, toutes deux disponibles dès le plan gratuit (100 emails/jour).

Comparaison entre API REST et SMTP Relay

Comparatif technique

CritèreAPI RESTSMTP Relay
Endpointhttps://api.mailgun.net/v3/{domain}/messages (US)smtp.mailgun.org ports 587/465
AuthentificationHTTP Basic Auth (api:YOUR_API_KEY)SASL/PLAIN (postmaster@ + SMTP password)
Rate limitNon documenté (Domains API : 300 req/min)Dépend de l'IP et du plan
Destinataires/reqJusqu'à 1 000 (to + cc + bcc combinés)1 email = 1 connexion SMTP
TemplatesVariables avec syntaxe {{variable}}Via header X-Mailgun-Variables
Schedulingo:deliverytime (jusqu'à 3 jours, 7j si stockage 7j+)Via header X-Mailgun-Deliver-By
TrackingNatif (o:tracking, o:track-clicks, o:track-opens)Via headers X-Mailgun-Track*
CompatibilitéRequiert SDK ou HTTP clientTout système supportant SMTP
Cas d'usage idéalApps modernes, batch, personnalisation avancéeLegacy, plugins CMS, serveurs mail

Quand choisir l'API REST ?

L'API REST est la méthode recommandée par Mailgun pour toute nouvelle intégration. Elle est accessible à POST https://api.mailgun.net/v3/{domain}/messages pour la région US, ou api.eu.mailgun.net pour l'EU.

Avantages clés :

  • Batch sending : envoi de jusqu'à 1 000 destinataires dans une seule requête avec personnalisation via recipient variables
  • Templates stockés : syntaxe Handlebars avec conditions, boucles, helpers personnalisés
  • Scheduling : programmation d'envoi jusqu'à 3 jours à l'avance (7 jours si votre plan inclut 7+ jours de stockage)
  • Rate limit headers : X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset pour monitoring

Exemple d'envoi avec personnalisation :

curl -s --user 'api:YOUR_API_KEY' \
  https://api.mailgun.net/v3/mail.captaindns.com/messages \
  -F from='Notifications <no-reply@mail.captaindns.com>' \
  -F to='user1@captaindns.com' \
  -F to='user2@captaindns.com' \
  -F subject='Nouvelle notification' \
  -F text='Bonjour {{prenom}}, vous avez {{count}} notifications.' \
  -F recipient-variables='{"user1@captaindns.com":{"prenom":"Jean","count":"3"},"user2@captaindns.com":{"prenom":"Marie","count":"7"}}' \
  -F o:tag='notification' \
  -F o:tracking='yes'

SDKs officiels : Mailgun maintient des SDKs pour Go, Node.js, PHP, Python, Ruby et Java qui encapsulent l'API REST et simplifient l'intégration.

Quand choisir le SMTP Relay ?

Le SMTP Relay est idéal pour les systèmes legacy ou les applications ne supportant que SMTP.

Configuration officielle :

SMTP server: smtp.mailgun.org (US) ou smtp.eu.mailgun.org (EU)
SMTP user: postmaster@mail.captaindns.com (ou utilisateur SMTP personnalisé)
SMTP password: [mot de passe SMTP du domaine]
Port: 587 (STARTTLS recommandé) ou 465 (TLS direct) ou 2525 (fallback GCE)

Point critique : l'authentification SMTP utilise le mot de passe SMTP du domaine, distinct de la clé API. Le username est l'adresse postmaster@ de votre domaine vérifié (ou un utilisateur SMTP personnalisé créé dans le dashboard).

Headers propriétaires X-Mailgun-* : permettent d'accéder aux fonctionnalités avancées via SMTP (tags, tracking, templates, scheduling, variables). Liste complète :

  • X-Mailgun-Tag : tag pour statistiques (multiples possibles)
  • X-Mailgun-Track : activer/désactiver tracking global
  • X-Mailgun-Track-Clicks : tracking clics (yes/no/htmlonly)
  • X-Mailgun-Track-Opens : tracking ouvertures (yes/no)
  • X-Mailgun-Deliver-By : planification (format RFC 2822 ou timestamp Unix)
  • X-Mailgun-Template-Name : nom du template à utiliser
  • X-Mailgun-Variables : variables template (JSON)

Domain Verification : SPF, DKIM 2048 bits et alignement DMARC natif

La configuration DNS chez Mailgun génère les enregistrements nécessaires pour SPF, DKIM et l'alignement DMARC. Le processus s'effectue dans Sending > Domains > Domain settings > Domain verification.

Architecture avec Automatic Sender Security (recommandé)

Avec l'option Automatic Sender Security activée (recommandé), Mailgun génère 2 enregistrements CNAME DKIM pour la rotation automatique des clés :

Configuration Domain Verification Mailgun

Enregistrements requis (exemple pour mail.captaindns.com) :

TypeName/HostValueObjectif
TXTmail.captaindns.comv=spf1 include:mailgun.org ~allSPF
CNAMEpdk1._domainkey.mail.captaindns.compdk1._domainkey.XXXX.dkim1.mailgun.comDKIM rotation (sélecteur 1)
CNAMEpdk2._domainkey.mail.captaindns.compdk2._domainkey.XXXX.dkim1.mailgun.comDKIM rotation (sélecteur 2)
MXmail.captaindns.commxa.mailgun.org (priorité 10)Bounces/Inbound
MXmail.captaindns.commxb.mailgun.org (priorité 10)Bounces/Inbound

Note région EU : Pour l'EU, les enregistrements MX utilisent mxa.eu.mailgun.org et mxb.eu.mailgun.org.

Avantages de cette architecture :

  • Rotation automatique des clés DKIM : les deux sélecteurs (pdk1 et pdk2) permettent à Mailgun de changer les clés tous les 120 jours sans interruption de service
  • Clés DKIM 2048 bits par défaut (configurations manuelles TXT peuvent utiliser 1024 bits, mais 2048 recommandé)
  • Aucun enregistrement CNAME de tracking requis par défaut : Mailgun utilise mailgun.org (ou eu.mailgun.org pour l'EU)
  • Sélecteurs DKIM : pdk1 et pdk2 pour Automatic Security, ou mx pour configuration manuelle TXT

Return-Path et alignement SPF : un avantage majeur

Le Return-Path (Envelope From) est crucial pour l'alignement DMARC. Mailgun utilise automatiquement votre domaine pour le Return-Path au format bounce+UNIQUEID@mail.captaindns.com :

  • SPF passe automatiquement car l'enregistrement include:mailgun.org autorise les IP Mailgun à envoyer pour votre domaine
  • L'alignement SPF fonctionne en mode relaxed (le Return-Path bounce+id@mail.captaindns.com correspond au domaine parent mail.captaindns.com)
  • Pas besoin de configuration séparée : contrairement à d'autres providers, Mailgun ne nécessite pas de sous-domaine dédié pour le bounce domain

Différence avec les concurrents :

  • SendGrid : utilise un sous-domaine personnalisable (em1234.captaindns.com)
  • Amazon SES : nécessite Custom MAIL FROM pour l'alignement SPF
  • Mailgun : utilise directement votre domaine vérifié

Pour une politique DMARC stricte (aspf=s), l'alignement SPF échouera si vous envoyez depuis un sous-domaine différent du Return-Path. La solution est de s'appuyer sur DKIM pour l'alignement DMARC, qui supporte le mode strict (adkim=s).

Le tracking domain remplace les domaines Mailgun dans les liens trackés par votre propre domaine. Par défaut, Mailgun utilise email.mail.captaindns.com pointant vers mailgun.org (US) ou eu.mailgun.org (EU) via CNAME.

Configuration optionnelle HTTPS : Mailgun génère automatiquement un certificat Let's Encrypt une fois le CNAME vérifié.

Migration vers DKIM 2048 bits

Pour migrer une configuration TXT manuelle (clés 1024 bits) vers Automatic Sender Security (2048 bits), il suffit d'activer Automatic Sender Security dans le dashboard puis de créer les 2 nouveaux CNAME DKIM. La transition est fluide grâce aux deux sélecteurs.

Flux d'authentification email : de l'API à la délivrabilité

Flux d'authentification email Mailgun avec DKIM, SPF et DMARC

Quand vous envoyez via Mailgun :

  1. Votre application appelle l'API REST ou utilise SMTP
  2. Mailgun signe le message avec votre clé DKIM (domaine d=mail.captaindns.com)
  3. Mailgun utilise votre domaine dans le Return-Path (bounce+id@mail.captaindns.com)
  4. Le serveur destinataire vérifie SPF (IP d'envoi), DKIM (signature), puis DMARC (alignement)
  5. SPF passe : include:mailgun.org autorise les IP Mailgun, Return-Path utilise votre domaine
  6. DKIM passe : signature d=mail.captaindns.com correspond au From header
  7. DMARC passe : au moins SPF ET DKIM sont alignés (double validation)

Alignement DMARC : configuration pour p=reject

Ce qui fonctionne (et ce qui casse)

Alignement DKIM :

ConfigurationAligné ?DMARC via DKIM ?
Domaine avec DKIM activé (TXT ou CNAME)OuiOui

Alignement SPF :

ConfigurationAligné ?DMARC via SPF ?
Return-Path utilise votre domaine (natif)OuiOui
aspf=r (relaxed, défaut)OuiOui
aspf=s (strict) + envoi depuis sous-domaineNonNon (mismatch subdomain)

Enregistrement DMARC recommandé

_dmarc.captaindns.com  TXT  "v=DMARC1;p=reject;adkim=r;aspf=r;rua=mailto:dmarc@captaindns.com"

Points clés :

  • adkim=r et aspf=r : alignement relaxed (autorise les sous-domaines)
  • Progressez de p=none → p=quarantine → p=reject
  • Surveillez les rapports rua avant de durcir
  • Avantage Mailgun : double alignement (SPF + DKIM) natif, meilleure protection qu'avec DKIM seul

Tableau récapitulatif DNS complet

TypeHost/NameValueObligatoireNotes
TXTmail.captaindns.comv=spf1 include:mailgun.org ~all✅ OuiSPF identique US/EU
CNAMEpdk1._domainkey.mail.captaindns.compdk1._domainkey.XXXX.dkim1.mailgun.com✅ OuiDKIM rotation auto
CNAMEpdk2._domainkey.mail.captaindns.compdk2._domainkey.XXXX.dkim1.mailgun.com✅ OuiDKIM rotation auto
MXmail.captaindns.commxa.mailgun.org (priorité 10)✅ OuiBounces/Inbound
MXmail.captaindns.commxb.mailgun.org (priorité 10)✅ OuiBounces/Inbound
TXT_dmarc.captaindns.comv=DMARC1;p=reject;adkim=r;aspf=r;...RecommandéDMARC policy
CNAMEemail.mail.captaindns.commailgun.org ou eu.mailgun.orgOptionnelTracking domain

IP dédiée vs IP partagée : stratégie de délivrabilité

Mailgun recommande officiellement une IP dédiée à partir de 1 million d'emails par mois. En dessous, l'IP partagée offre généralement une meilleure délivrabilité.

IP partagée (plans Free, Foundation, Growth de base)

Avantages :

  • Aucun warm-up nécessaire
  • Réputation maintenue par Mailgun
  • Idéale pour volumes faibles ou irréguliers
  • Meilleure délivrabilité initiale que sur IP dédiée froide

Inconvénients :

  • Exposition aux risques de réputation liés aux autres expéditeurs du pool (rare chez Mailgun grâce aux contrôles stricts)

IP dédiée (Foundation 100k+, Growth, Scale, Enterprise)

Le plan Foundation 100k inclut 1 IP dédiée (à partir de 75$/mois). Chaque IP supplémentaire coûte 59$/IP/mois.

Recommandation officielle : 1 IP dédiée pour environ 1 million d'emails par mois minimum.

Avantages :

  • Réputation isolée et contrôlable
  • Fonction d'IP Warmup automatique sur 15 étapes (~15+ jours)
  • Possibilité de séparer les flux (transactionnel vs marketing) via IP Pools

IP Warmup automatique : Mailgun propose un warm-up en 15 étapes progressives :

ÉtapeLimite quotidienneLimite horaireDurée
11 00010024h
22 500~10024h
35 000Progressive24h
...ProgressiveProgressive...
15Capacité totaleSans limiteAtteint J15+

Le système avance d'une étape toutes les 24 heures si les limites sont atteintes. Le trafic excédentaire est automatiquement routé vers les IP partagées ou autres IP dédiées disponibles.

IP Pools : Disponibles sur les plans Scale et supérieurs. Permettent de :

  • Séparer emails transactionnels vs marketing
  • Différents clients/marques (multi-tenant)
  • Dynamic IP Pools : assignation automatique basée sur la santé de réputation

Note importante : Les IP dédiées sont liées à une région (US ou EU). Une migration de région nécessite une nouvelle IP et un nouveau warm-up.

Quand choisir une IP dédiée ?

Vous avez besoin d'une IP dédiée si :

  • Volume régulier > 1 million emails/mois
  • Besoin de séparer réputation transactionnel vs marketing
  • Exigences de whitelisting client ou conformité réglementaire
  • Volume > 2,5 millions emails/mois : plusieurs IP dédiées recommandées

Restez sur IP partagée si :

  • Volume < 1 million emails/mois
  • Envois irréguliers ou sporadiques
  • Démarrage d'activité sans historique
  • Purement transactionnel faible volume

Tarification 2026 et évolution récente

Plans Send (janvier 2026)

PlanPrix/moisEmails inclusOverage (/1000)Log retentionIP dédiée
Free0 $100/jourN/A1 jourNon
FlexPay-per-use1 000 gratuits/mois2,00 $ ⚠️5 joursNon
Foundation 50k35 $50 000~1,30 $5 joursNon
Foundation 100k75 $100 000~1,30 $5 jours1 incluse
Growth80-650 $100k-1MVariable15 jours1 incluse
Scale 100k90 $100 000~0,80-1,10 $30 jours1 incluse
Scale (max)1 250 $2,5MVariable30 jours1 incluse
EnterpriseSur devis2,5M+Négocié30 joursMultiples

Évolution tarifaire récente

⚠️ Changement majeur (1er décembre 2025) : Le plan Flex est passé de 1,00 $ à 2,00 $ par 1 000 emails - une augmentation de 100%. Cette hausse significative rend les plans Foundation beaucoup plus attractifs pour les volumes > 25 000 emails/mois.

Analyse économique :

  • Plan Flex : 50 000 emails = 49 000 payants × 0,002 = 98 $
  • Plan Foundation 50k : 50 000 emails = 35 $ (économie de 63 $)
  • Seuil de rentabilité : le plan Foundation devient rentable dès ~18 000 emails/mois

Plans Optimize (outils de délivrabilité)

PlanPrix/moisValidationsTests inboxPreviews
Pilot49 $2 50025500
Starter99 $5 000501 000
ContractSur devisPersonnaliséPersonnaliséPersonnalisé

Réductions annuelles

Non documentées publiquement. Les clients Enterprise rapportent des remises de 10%+ négociables.

Tarification US vs EU

La tarification est standardisée mondialement en USD. Pas de différence régionale documentée entre US et EU.

Limites techniques et quotas

LimiteValeurNotes
Taille max email25 MBCorps + pièces jointes + en-têtes
Destinataires/message1 000To + Cc + Bcc combinés
Paramètres send options16 KBParamètres o:, h:, v:, t:
Templates/domaine100Limite stricte
Versions/template10-
Domaines (Free)5-
Domaines (payant)1 000-
Destinataires sandbox5Doivent être vérifiés
Rate limit Domains API300 req/minSeul endpoint documenté
Rate limit envoi (nouveaux comptes)100 messages/heureAvant vérification business
Scheduling max3 jours7 jours si plan avec 7j+ storage

Rétention des données

DonnéeRétention
Logs événements (Free)1 jour
Logs événements (Foundation)5 jours
Logs événements (Growth)15 jours
Logs événements (Scale)30 jours (max)
Contenu messages1-7 jours (configurable)
Stats horaires60 jours
Stats quotidiennes1 an
Stats mensuellesIndéfini
Logs sécurité critiques365 jours

Gestion des bounces et suppressions

Hard bounce (échec permanent)

ComportementDétail
ActionAdresse ajoutée à la liste de suppression
Durée blocageIndéfinie (jusqu'à suppression manuelle)
Erreur renvoyée"Not delivering to previously bounced address"

Soft bounce (échec temporaire)

ComportementDétail
RetryAutomatique pour les soft bounces immédiats
DuréeJusqu'au succès ou classification permanente
ConversionAprès multiples échecs, ajout à la liste bounce

Spam complaints (FBL)

Mailgun s'inscrit automatiquement aux Feedback Loops des principaux FAI. Les plaintes déclenchent :

  • Ajout automatique à la liste Complaints
  • Webhook complained envoyé
  • Blocage des envois futurs vers cette adresse

FAI supportés : Yahoo, Microsoft/Outlook, Comcast, Cox, Fastmail, et autres via Universal Feedback Loop. Note : Gmail ne fournit pas de FBL traditionnel.

Unsubscribe automatique

Mailgun ajoute automatiquement :

  • En-tête List-Unsubscribe
  • En-tête List-Unsubscribe-Post: List-Unsubscribe=One-Click

Conforme RFC 8058 et aux exigences Gmail/Yahoo pour les expéditeurs bulk (5000+ messages/jour).

API listes de suppression

ListeEndpoint
BouncesGET/POST/DELETE /v3/{domain}/bounces
ComplaintsGET/POST/DELETE /v3/{domain}/complaints
UnsubscribesGET/POST/DELETE /v3/{domain}/unsubscribes
AllowlistGET/POST/DELETE /v3/{domain}/allowlist

L'Allowlist empêche l'ajout d'adresses à la liste bounces mais n'override pas les Complaints ou Unsubscribes.

Event Webhook et tracking en temps réel

Le webhook d'événements permet de recevoir en temps réel les notifications de delivery, engagement et compliance.

Événements disponibles

  • Delivery : accepted, delivered, temporary_fail, permanent_fail
  • Engagement : opened, clicked
  • Compliance : complained, unsubscribed

Format payload JSON

{
  "signature": {
    "timestamp": "1529006854",
    "token": "a8ce0edb2dd8301dee6c2405235584e45aa91d1e9f979f3de0",
    "signature": "d2271d12299f6592d9d44cd9d250f0704e4674c30d79d07c47a66f95ce71cf55"
  },
  "event-data": {
    "event": "delivered",
    "timestamp": 1529006854.329574,
    "id": "DACSsAdVSeGpLid7TN03WA",
    "recipient": "recipient@captaindns.com",
    "tags": [],
    "message": {
      "headers": {
        "message-id": "20180618211821.captaindns.com"
      }
    }
  }
}

Retry policy

Code réponseAction
200Succès, pas de retry
406Rejeté, pas de retry
AutreRetry selon planning

Planning de retry : 5min → 10min → 15min → 1h → 2h → 4h (total : 8 heures)

Sécurité (signature HMAC)

ÉlémentValeur
AlgorithmeHMAC-SHA256
CléWebhook Signing Key (Control Panel → Account Security)
CalculHMAC-SHA256(timestamp + token, signingKey)

Exemple Python :

import hmac, hashlib
def verify(api_key, token, timestamp, signature):
    expected = hmac.new(api_key.encode(), f"{timestamp}{token}".encode(), 
                        hashlib.sha256).hexdigest()
    return signature == expected

Configuration

  • Jusqu'à 3 URLs par type d'événement par domaine
  • Configuration au niveau domaine (pas compte)
  • API : POST /v3/domains/{domain}/webhooks

Templates Handlebars

Mailgun utilise Handlebars (version personnalisée) pour les templates stockés.

Syntaxe des variables

ContexteSyntaxe
Templates stockés{{variable}}
Batch sending inline (API)%recipient.variable%

Conditions et boucles

{{#if condition}}
  Contenu si vrai
{{else if autreCondition}}
  Contenu alternatif
{{else}}
  Contenu par défaut
{{/if}}

{{#unless condition}}
  Contenu si faux
{{/unless}}

{{#equal variable "valeur"}}
  Contenu si égal
{{/equal}}

{{#each tableau}}
  <li>{{this.propriete}}</li>
{{/each}}

{{#with objet}}
  {{proprieteImbriquee}}
{{/with}}

Limites templates

LimiteValeur
Templates par domaine100
Versions par template10
Taille templateNon documentée
Partials (import)Non supporté

Fonctionnalités additionnelles

Email Validation API

AttributValeur
Endpoint singleGET /v4/address/validate?address=...
Endpoint bulkPOST /v4/address/validate/bulk/{list_id}
Base données450+ milliards d'emails
Tarif Foundation1,20 $/100 validations
Tarif Scale5 000 incluses, puis 0,80 $/100

Validations effectuées : syntaxe RFC, MX records, existence mailbox, bounces réseau Mailgun, adresses à risque, adresses role-based, emails jetables, typos domaine, domaines catch-all.

Inbound Parse (Routes)

Permet de recevoir des emails et les transférer vers une URL webhook :

Filtres : match_recipient(), match_header(), catch_all()
Actions : forward("https://url"), forward("email@"), store(), stop()

Retry inbound : jusqu'à 8 heures (10min, 15min, 30min, 1h, 2h, 4h) Rétention messages stockés : 3 jours

Attachments

LimiteValeur
Taille totale message25 MB (corps + attachments + headers)
Types fichiersAucune restriction documentée
Inline (CID)Supporté via paramètre inline

AMP for Email

Supporté depuis 2019 via le paramètre amp-html. Nécessite :

  • Enregistrement comme expéditeur AMP auprès de Google
  • SPF, DKIM, DMARC configurés
  • Fallback HTML obligatoire

Sécurité et conformité

Certifications

CertificationStatut
ISO 27001✅ Certifié
ISO 27701✅ Certifié (privacy)
SOC 2 Type I✅ Certifié
SOC 2 Type II✅ Certifié
SOC 1 (SSAE-16)✅ Certifié
PCI-DSS✅ Conforme (SAQ-A)
CSA Star Level 1✅ Conforme

RGPD

ÉlémentDétail
DPADisponible : mailgun.com/legal/dpa/
Localisation données EUAllemagne
Endpoints EUapi.eu.mailgun.net, smtp.eu.mailgun.org
Résidence donnéesMessages jamais transférés hors région
DPODédié, basé en EU

HIPAA

ÉlémentDétail
Statut✅ Conforme
BAADisponible : mailgun.com/legal/hipaa-baa/
PrérequisConfiguration chiffrement client, consentement patient, signature BAA

Chiffrement TLS

VersionStatut
TLS 1.0❌ Déprécié (mars 2021)
TLS 1.1❌ Déprécié (mars 2021)
TLS 1.2✅ Supporté
TLS 1.3✅ Supporté

Chiffrement au repos : AES-256

Authentification avancée

FonctionnalitéDisponibilité
2FA✅ Tous les plans
SSO✅ Scale et Enterprise
SAML 2.0✅ Scale et Enterprise
IdP supportésOkta, Auth0, OneLogin, Azure AD, ADFS, AWS IAM
RBAC✅ Scale et Enterprise (Admin, Developer, Analyst, Support)

Plan d'action : configuration en 6 étapes

1. Créer le compte et configurer le domaine

  • Créer un compte Mailgun sur mailgun.com/signup
  • Choisir la région (US ou EU selon vos besoins RGPD)
  • Un domaine sandbox est créé automatiquement (100 emails/jour)

2. Vérifier le domaine (Domain Verification)

  • Aller dans Sending > Domains > Add New Domain
  • Saisir votre domaine d'envoi (ex: mail.captaindns.com)
  • Activer Automatic Sender Security (recommandé)
  • Créer les enregistrements DNS chez votre registrar :
    1. TXT SPF : v=spf1 include:mailgun.org ~all
    2. CNAME DKIM pdk1 : pdk1._domainkey.mail.captaindns.com
    3. CNAME DKIM pdk2 : pdk2._domainkey.mail.captaindns.com
    4. MX mxa : mxa.mailgun.org (priorité 10)
    5. MX mxb : mxb.mailgun.org (priorité 10)
  • Vérifier la propagation DNS (24-48h)

3. Publier l'enregistrement DMARC

Créer l'enregistrement DMARC sur votre domaine principal :

_dmarc.captaindns.com  TXT  "v=DMARC1;p=none;rua=mailto:dmarc@captaindns.com;aspf=r;adkim=r"

Commencer par p=none pour monitoring, puis passer à p=quarantine puis p=reject une fois les rapports validés.

4. Choisir et configurer la méthode d'envoi

Option A : API REST

  • Générer une API key dans Settings > API Keys
  • Choisir les permissions (Full Access ou Domain sending keys pour scope limité)
  • Implémenter l'endpoint POST /v3/{domain}/messages
  • Créer des templates dans Sending > Templates si besoin

Option B : SMTP Relay

  • Récupérer le mot de passe SMTP du domaine dans Sending > Domains > Domain settings > SMTP credentials
  • Configurer votre app/plugin/serveur mail :
    • Host : smtp.mailgun.org (US) ou smtp.eu.mailgun.org (EU)
    • Port : 587 (STARTTLS recommandé)
    • User : postmaster@mail.captaindns.com
    • Password : le mot de passe SMTP du domaine

5. Configurer les webhooks

  • Aller dans Sending > Webhooks
  • Définir l'URL de votre endpoint (HTTPS recommandé)
  • Sélectionner les événements (delivered, bounced, opened, clicked, etc.)
  • Récupérer la Webhook Signing Key pour valider les signatures HMAC

6. Tester et monitorer

  • Envoyer un email test via API ou SMTP
  • Vérifier dans Sending > Logs que l'email est bien délivré
  • Vérifier les événements webhook sur votre endpoint
  • Contrôler les statistiques (deliverability, open rate, bounce rate)
  • Pour passer en production, sortir du mode sandbox en contactant le support Mailgun (vérification business)

Guides techniques : autres plateformes email transactionnel

Decouvrez nos guides complets pour les autres solutions d'email transactionnel :

FAQ

Quelle différence entre clé API primaire et Domain Sending Keys ?

La clé API primaire (Primary Account API Key) donne accès CRUD complet à toutes les API du compte. Les Domain Sending Keys sont limitées à l'envoi uniquement (POST /messages) pour un domaine spécifique. Utilisez les Domain Sending Keys dans vos apps pour limiter la surface d'attaque en cas de compromission.

Pourquoi Mailgun génère-t-il deux sélecteurs DKIM (pdk1 et pdk2) ?

Les deux sélecteurs permettent la rotation automatique des clés DKIM tous les 120 jours sans interruption de service. Lorsque Mailgun veut renouveler les clés pour des raisons de sécurité, il génère une nouvelle clé sur pdk2 pendant que pdk1 est encore actif, puis bascule progressivement le trafic. Cela évite toute interruption de délivrabilité lors du changement de clé.

Dois-je configurer un Custom MAIL FROM comme avec Amazon SES ?

Non, contrairement à Amazon SES qui nécessite Custom MAIL FROM pour l'alignement SPF, Mailgun utilise automatiquement votre domaine vérifié dans le Return-Path (bounce+id@mail.captaindns.com). L'alignement SPF DMARC fonctionne nativement dès la configuration du domaine, sans configuration séparée.

Comment fonctionne le mode test sans consommer de crédits ?

Utilisez le paramètre o:testmode=yes (API) ou le header X-Mailgun-Drop-Message: yes (SMTP). Les messages sont acceptés mais non délivrés, générant un événement delivered avec code 650. Idéal pour tester la structure des requêtes et le format des payloads sans envoyer réellement d'emails.

Quelle est la limite réelle de destinataires par appel API ?

1 000 destinataires maximum par appel (to + cc + bcc combinés). Au-delà, diviser en plusieurs appels. Pour envoyer à 10 000 personnes, il faut 10 appels API. Utilisez les recipient variables pour personnaliser le contenu de chaque destinataire dans un même batch.

Le plan Flex est-il adapté pour de la production à volume variable ?

Depuis le doublement du tarif (2,00$/1000 emails en décembre 2025), le plan Flex est devenu moins compétitif. Pour plus de 18 000 emails/mois, le plan Foundation 50k (35$/mois) est plus rentable. Flex reste intéressant pour des volumes très faibles et irréguliers (< 10 000/mois) ou pour tester avant de s'engager.

Dois-je prendre une IP dédiée pour mon projet ?

Probablement non. Une IP dédiée nécessite un volume minimum de 1 million d'emails par mois, avec des envois réguliers. Elle impose un warm-up de 15+ jours et coûte 59$/IP/mois supplémentaire (ou incluse dès Foundation 100k). Si votre volume est inférieur ou si vos envois sont irréguliers, restez sur IP partagée. La réputation Mailgun sur IP partagée est excellente.

Les rate limits API sont-ils documentés ?

Non, Mailgun ne documente pas publiquement les rate limits spécifiques par endpoint, sauf pour l'API Domains (300 req/min). Les nouveaux comptes peuvent être limités à 100 messages/heure avant vérification business. Les headers X-RateLimit-* dans les réponses indiquent votre quota en temps réel. En cas de 429, implémenter un backoff exponentiel.

Glossaire

  • API REST : API HTTP de Mailgun pour l'envoi d'emails transactionnels. Endpoint principal : POST /v3/{domain}/messages. Authentification : HTTP Basic Auth (api:YOUR_API_KEY). Méthode recommandée pour toute nouvelle intégration.

  • SMTP Relay : Serveur SMTP de Mailgun (smtp.mailgun.org) permettant d'envoyer via le protocole SMTP standard. Authentification : SASL/PLAIN (postmaster@ + SMTP password). Ports disponibles : 587 (STARTTLS), 465 (TLS direct), 2525 (fallback GCE).

  • Domain Verification : Configuration DNS pour authentifier votre domaine avec Mailgun. Génère les enregistrements SPF, DKIM, MX. Avec Automatic Sender Security : 2 CNAME DKIM (pdk1 et pdk2) pour rotation automatique tous les 120 jours, clés 2048 bits par défaut.

  • Return-Path (Envelope From) : Adresse technique utilisée pour le routage SMTP et les bounces. Mailgun utilise automatiquement votre domaine (bounce+id@mail.captaindns.com), permettant l'alignement SPF relaxed pour DMARC sans configuration séparée. Différence majeure avec SendGrid (sous-domaine em1234) et Amazon SES (Custom MAIL FROM requis).

  • Automatic Sender Security : Option recommandée pour Domain Verification. Génère 2 CNAME DKIM au lieu de TXT, permet la rotation automatique des clés DKIM tous les 120 jours, et utilise clés 2048 bits par défaut.

  • Recipient Variables : Mécanisme pour personnaliser le contenu de chaque destinataire dans un envoi batch. Syntaxe : %recipient.variable% dans le message, avec un JSON mappant chaque email à ses variables. Permet d'envoyer jusqu'à 1 000 versions personnalisées en un seul appel API.

  • IP Warmup : Processus automatique de montée en charge d'une IP dédiée neuve. Calendrier sur 15 étapes : de 1 000 emails/jour (J1) à capacité totale (J15+). Le système avance d'une étape toutes les 24h si les limites sont atteintes. Le trafic excédentaire est routé vers les IP partagées.

  • IP Pools : Groupes d'IP dédiées assignables à différents flux (transactionnel vs marketing, par client, par marque). Disponibles sur plans Scale et Enterprise. Permettent de séparer la réputation. Dynamic IP Pools : assignation automatique basée sur la santé de réputation.

  • Event Webhook : Endpoint HTTP appelé par Mailgun lors d'événements (accepted, delivered, opened, clicked, bounced, complained, unsubscribed). Configuration : jusqu'à 3 URLs par type d'événement. Retry pendant 8h en cas d'échec. Sécurité : signature HMAC-SHA256.

  • Handlebars : Langage de templating utilisé par Mailgun pour les templates stockés. Supporte variables {{variable}}, conditions {{#if}}, boucles {{#each}}, helpers {{#equal}}. Limite : 100 templates par domaine, 10 versions par template. Pas de support des partials.

  • Sandbox Mode : Mode test qui valide le format des requêtes sans envoyer réellement d'email. Active via o:testmode=yes (API) ou X-Mailgun-Drop-Message: yes (SMTP). Génère un événement delivered avec code 650. Ne consomme pas de crédits. Limite : 5 destinataires vérifiés.

  • Suppressions : Listes de blocage maintenues automatiquement par Mailgun (Bounces, Complaints, Unsubscribes). Les adresses sont supprimées indéfiniment par défaut. Gestion via API : GET/POST/DELETE /v3/{domain}/{bounces|complaints|unsubscribes}. Allowlist : empêche l'ajout à Bounces mais n'override pas Complaints/Unsubscribes.

  • Domain Sending Keys : Clés API limitées à l'envoi uniquement (POST /messages) pour un domaine spécifique. Contrairement à la clé API primaire (accès CRUD complet), elles réduisent la surface d'attaque. Recommandées pour les apps en production.

  • RBAC API Keys (Scale+) : Clés API avec rôles prédéfinis : Admin (lecture/écriture complète), Developer (accès technique complet), Analyst (lecture seule métriques), Support (lecture + gestion suppressions). Disponibles sur plans Scale et Enterprise uniquement.

Sources officielles

Articles similaires