Mailpit : serveur SMTP de test auto-hébergé sur votre VPS

Pourquoi remplacer MailHog par Mailpit

Ce que Mailpit apporte en pratique

• Interface moderne avec recherche full-text, affichage HTML/texte, prévisualisation mobile et inspection des en-têtes
• Binaire unique Go compilé statiquement — aucune dépendance système, tourne dans un conteneur de 20 Mo
• Consommation mémoire au repos inférieure à 50 Mo, stable même avec des milliers d'e-mails en session
• API REST rétro-compatible MailHog (/api/v1/messages, /api/v1/search) pour les scripts existants
• Support SMTP authentifié, TLS optionnel, et contrôle d'accès par réseau
• Webhook configurable pour notifier un endpoint externe à chaque réception d'e-mail

Prérequis

Déployer Mailpit en 5 étapes

1. 01

   Créer le répertoire et le fichier Compose

   mkdir -p /opt/mailpit && cd /opt/mailpit

   Créez le fichier docker-compose.yml suivant :

   services:
     mailpit:
       image: axllent/mailpit:latest
       container_name: mailpit
       restart: unless-stopped
       ports:
         - "127.0.0.1:1025:1025"
         - "127.0.0.1:8025:8025"
       environment:
         MP_MAX_MESSAGES: 500
         MP_SMTP_AUTH_ACCEPT_ANY: "true"
         MP_SMTP_AUTH_ALLOW_INSECURE: "true"
         MP_UI_AUTH: "admin:changeme"
       volumes:
         - mailpit_data:/data
   volumes:
     mailpit_data:

   Les ports sont liés à 127.0.0.1 uniquement : Mailpit n'est jamais exposé directement sur l'IP publique. La variable MP_UI_AUTH active l'authentification HTTP basique sur l'interface web — changez le mot de passe. MP_MAX_MESSAGES limite le nombre d'e-mails conservés en mémoire par session.

2. 02

   Démarrer le conteneur

   docker compose up -d
   docker compose logs -f mailpit

   La ligne starting on [::]:1025 confirme que le serveur SMTP écoute. Vérifiez que les ports sont bien liés à localhost :

   ss -tlnp | grep -E '1025|8025'

   Attendu : 127.0.0.1:1025 et 127.0.0.1:8025 uniquement — jamais 0.0.0.0.

3. 03

   Configurer le reverse proxy Nginx

   Créez /etc/nginx/sites-available/mailpit :

   server {
       listen 443 ssl;
       server_name mail.votre-domaine.com;
   
       ssl_certificate     /etc/letsencrypt/live/mail.votre-domaine.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/mail.votre-domaine.com/privkey.pem;
   
       location / {
           proxy_pass         http://127.0.0.1:8025;
           proxy_http_version 1.1;
           proxy_set_header   Upgrade $http_upgrade;
           proxy_set_header   Connection "upgrade";
           proxy_set_header   Host $host;
           proxy_read_timeout 86400;
       }
   }

   Le proxy_read_timeout 86400 est nécessaire pour les connexions WebSocket utilisées par l'interface en temps réel. Activez le vhost et rechargez Nginx :

   ln -s /etc/nginx/sites-available/mailpit /etc/nginx/sites-enabled/
   nginx -t && systemctl reload nginx

   Obtenez un certificat Let's Encrypt si ce n'est pas déjà fait :

   certbot --nginx -d mail.votre-domaine.com

4. 04

   Tester l'envoi avec curl

   Vérifiez que le serveur SMTP reçoit bien un message :

   curl --url 'smtp://127.0.0.1:1025' \
     --mail-from '[email protected]' \
     --mail-rcpt '[email protected]' \
     --upload-file - <<EOF
   From: [email protected]
   To: [email protected]
   Subject: Test Mailpit
   
   Corps du message de test.
   EOF

   Ouvrez ensuite https://mail.votre-domaine.com dans votre navigateur. Le message doit apparaître dans l'interface. Si vous avez configuré MP_UI_AUTH, saisissez les identifiants au prompt HTTP basique.

5. 05

   Configurer votre application pour pointer vers Mailpit

   Dans votre fichier .env (Laravel, Symfony, n8n, Django…), remplacez la configuration SMTP par :

   MAIL_HOST=127.0.0.1
   MAIL_PORT=1025
   MAIL_ENCRYPTION=null
   MAIL_USERNAME=null
   MAIL_PASSWORD=null

   Pour les applications tournant dans Docker sur le même hôte, utilisez le nom du réseau Docker ou l'IP gateway (172.17.0.1 par défaut) à la place de 127.0.0.1.

Mailpit en CI/CD : tester les e-mails dans le pipeline

Intégration CI/CD par framework

1. 06

   GitHub Actions — service Mailpit

   services:
     mailpit:
       image: axllent/mailpit:latest
       ports:
         - 1025:1025
         - 8025:8025

   Dans vos variables d'environnement du job, définissez MAIL_HOST=127.0.0.1 et MAIL_PORT=1025. Mailpit accepte tout e-mail sans authentification par défaut — aucune configuration SMTP supplémentaire n'est nécessaire.

2. 07

   Laravel — PHPUnit

   Dans phpunit.xml, remplacez le transport par SMTP :

   <env name="MAIL_MAILER" value="smtp"/>
   <env name="MAIL_HOST" value="127.0.0.1"/>
   <env name="MAIL_PORT" value="1025"/>

   Dans votre test, envoyez le mail puis interrogez l'API Mailpit pour vérifier la réception :

   $response = Http::get('http://127.0.0.1:8025/api/v1/messages');
   $this->assertSame($response->json('total'), 1);
   $this->assertStringContainsString(
       'Bienvenue',
       $response->json('messages.0.Subject')
   );

3. 08

   Django — pytest

   Dans settings.py (ou settings_test.py) :

   EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
   EMAIL_HOST = '127.0.0.1'
   EMAIL_PORT = 1025

   Dans votre test pytest, vérifiez via l'API Mailpit :

   import requests
   
   def test_welcome_email_sent():
       # déclencher l'envoi dans votre vue/service
       r = requests.get('http://127.0.0.1:8025/api/v1/messages')
       assert r.json()['total'] == 1
       assert 'Bienvenue' in r.json()['messages'][0]['Subject']

4. 09

   n8n — tests de workflow

   Dans le nœud Send Email de n8n, configurez le serveur SMTP sur 127.0.0.1:1025 sans authentification. Pour vérifier automatiquement qu'un workflow a bien déclenché un envoi, appelez GET http://127.0.0.1:8025/api/v1/messages depuis un nœud HTTP Request et validez le total dans un nœud IF.

Sécuriser l'accès à Mailpit

Dépannage — 4 cas fréquents

Mailpit vs MailHog vs Mailtrap vs Inbucket vs smtp4dev

Faites défiler le tableau

Cas d'usage avancés