Tester les emails Symfony en local sur votre Mac

Redirigez chaque email de Symfony Mailer vers un serveur SMTP local sur votre Mac avec une seule ligne MAILER_DSN, puis inspectez chaque message dès son arrivée.

Symfony Mailer se configure avec un seul DSN : passer à un outil de capture local se résume donc à changer une ligne. Pointez-le vers Mailbox, et chaque email envoyé par votre app Symfony arrive sur votre Mac — HTML rendu, texte brut, en-têtes et pièces jointes — au lieu d’atterrir dans une vraie boîte de réception.

1. Démarrez un serveur dans Mailbox

Ouvrez Mailbox. Au premier lancement, l’app crée un serveur sur le port 2525 — vérifiez qu’il est bien démarré. Si vous préférez ajouter un autre serveur, Mailbox lui attribue un port libre ; utilisez alors ce port dans les étapes suivantes.

2. Définissez le DSN

Dans .env.local (pour qu’il n’arrive jamais en production) :

MAILER_DSN=smtp://127.0.0.1:2525

N’incluez ni utilisateur ni mot de passe dans le DSN — Mailbox n’utilise ni authentification SMTP ni TLS. Videz le cache si vous avez modifié des variables d’environnement pendant que l’app tournait :

php bin/console cache:clear

3. Envoyez un email de test

Symfony intègre une commande prévue pour ça :

php bin/console mailer:test test@example.com

Le message apparaît immédiatement dans Mailbox. Les emails envoyés par vos contrôleurs, vos handlers Messenger et vos notifiers empruntent le même chemin.

Messenger et emails asynchrones

Si Messenger route SendEmailMessage vers un transport asynchrone, les emails ne sont envoyés que lorsqu’un worker consomme la file d’attente :

php bin/console messenger:consume async

Exécuter Symfony dans Docker

Dans un conteneur, 127.0.0.1 désigne le conteneur lui-même. Utilisez plutôt votre Mac :

MAILER_DSN=smtp://host.docker.internal:2525

La recipe Docker de Symfony ajoute aussi un service Mailpit nommé mailer dans compose.override.yaml. Quand il est présent, la CLI Symfony exporte son propre MAILER_DSN depuis Docker, qui l’emporte sur .env.local. Supprimez ce service, ou ajoutez-lui le label com.symfony.server.service-ignore: true.

Si le conteneur ne parvient toujours pas à se connecter, activez Autoriser l’accès réseau dans Mailbox (Réglages → Général) et redémarrez le serveur : il acceptera alors les connexions venant de l’extérieur de l’interface loopback.

Dépannage

  • « Connection could not be established » — le serveur Mailbox n’est pas démarré, ou le port est différent.
  • L’ancien DSN est toujours utilisé — une vraie variable d’environnement (y compris une variable exportée par la CLI Symfony depuis Docker) est prioritaire sur .env.local ; vérifiez avec php bin/console debug:dotenv.
  • Rien n’arrive, sans erreur — l’email attend dans la file d’attente Messenger ; lancez un worker.

Que vérifier ensuite

Lancez la vérification de compatibilité HTML de Mailbox sur vos templates d’emails Twig pour repérer le CSS qu’Outlook ou Gmail n’afficheront pas, et ouvrez l’aperçu mobile pour les voir sur un écran de la taille d’un téléphone.

Autres guides