Mailpit : intercepter tous les emails en local pendant le développement

Pendant le développement, les emails posent un problème récurrent : soit vous les envoyez vers de vraies adresses (risque d’envoyer des données de test à de vrais utilisateurs), soit vous désactivez l’envoi (et vous ne pouvez pas tester les emails), soit vous configurez un service de test tiers.

Mailpit offre une quatrième option : capturer tous les emails localement et les afficher dans une interface web.

Ce que fait Mailpit

Mailpit est un serveur SMTP local qui accepte tous les emails sans les envoyer. Chaque email capturé est visible dans une interface web avec rendu HTML, source MIME, en-têtes, et pièces jointes.

Vous configurez votre application pour envoyer vers localhost:1025, et Mailpit intercepte tout. L’interface web est disponible sur http://localhost:8025.

Installation

# macOS
brew install mailpit

# Linux
curl -sL https://raw.githubusercontent.com/axllent/mailpit/develop/install.sh | bash

# Docker
docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit

# Binaire direct (toutes plateformes)
# https://github.com/axllent/mailpit/releases

Démarrer Mailpit

mailpit
# Interface web : http://localhost:8025
# Serveur SMTP  : localhost:1025

Configurer votre application

Node.js / Nodemailer :

import nodemailer from 'nodemailer';

const transporter = nodemailer.createTransport({
  host: process.env.SMTP_HOST || 'localhost',
  port: parseInt(process.env.SMTP_PORT) || 1025,
  secure: false,
  ignoreTLS: true,
});

PHP / Laravel :

MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_ENCRYPTION=null

Python / Django :

# settings.py
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'localhost'
EMAIL_PORT = 1025

Variables d’environnement (approche générique) :

SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USER=
SMTP_PASS=

Fonctionnalités de l’interface

L’interface web de Mailpit affiche pour chaque email :

• Rendu HTML — exactement comme dans un client mail
• Texte brut — la version text/plain
• Source MIME — les en-têtes et le body brut
• Pièces jointes — téléchargeables directement
• Destinataires — To, CC, BCC tous visibles

Un bouton “Check” teste si le rendu est compatible avec les clients mail courants (Gmail, Outlook, Apple Mail) en s’appuyant sur les règles de compatibilité CSS email.

Utilisation avec Docker Compose

services:
  app:
    build: .
    environment:
      SMTP_HOST: mailpit
      SMTP_PORT: 1025
    depends_on:
      - mailpit

  mailpit:
    image: axllent/mailpit
    ports:
      - "8025:8025"
      - "1025:1025"

API REST

Mailpit expose une API REST pour accéder aux emails par programmation :

# Lister les emails
curl http://localhost:8025/api/v1/messages

# Récupérer un email spécifique
curl http://localhost:8025/api/v1/message/{id}

# Supprimer tous les emails
curl -X DELETE http://localhost:8025/api/v1/messages

Utile pour les tests end-to-end : après avoir déclenché un envoi d’email dans votre test, vous interrogez l’API Mailpit pour vérifier que l’email a bien été envoyé avec le bon contenu.

+ Les points forts

• Zéro risque d’envoi en production — les emails n’arrivent jamais à de vraies adresses
• Interface soignée — rendu fidèle, source consultable, pièces jointes gérées
• API REST — intégrable dans les tests automatisés
• Léger — un seul binaire, consommation mémoire minimale
• Successeur de MailHog — projet plus actif et maintenu que son prédécesseur populaire

- Les points faibles

• Pas de persistance par défaut — les emails sont perdus au redémarrage (configurable avec --db-file)
• Pas de vraie livraison — Mailpit ne peut pas relayer les emails vers de vraies adresses. Pour tester l’envoi réel tout en interceptant, il faut un service comme Mailtrap
• Pas de simulation de rebonds ou de spam — vous ne pouvez pas tester comment votre application gère les erreurs SMTP (email invalide, boîte pleine)

En résumé

Mailpit est devenu un standard dans les environnements de développement modernes. Que ce soit en local ou via Docker Compose, l’ajouter à votre stack prend cinq minutes et élimine définitivement le risque d’envoyer des emails de test à de vrais utilisateurs.

---

Voir aussi :

• ngrok — exposer l’environnement de dev local vers l’extérieur
• mkcert — configurer HTTPS pour l’environnement local