Tester les emails Rails en local sur votre Mac

Envoyez les emails Action Mailer de votre app Rails à un serveur SMTP local sur Mac. Configurez development.rb en une minute et inspectez chacun aussitôt.

Par défaut, Rails en développement tente de livrer les emails en SMTP et ignore silencieusement les erreurs de livraison : vous ne voyez donc les emails que dans le log — suffisant pour une vérification rapide, pénible quand vous devez voir le vrai HTML. Avec Mailbox, Action Mailer livre les emails à un serveur SMTP local sur votre Mac, et chacun s’affiche avec son rendu, ses en-têtes, sa partie texte brut et ses pièces jointes. Rien n’atteint 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. Configurez Action Mailer

Dans config/environments/development.rb :

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  address: "127.0.0.1",
  port: 2525
}
config.action_mailer.raise_delivery_errors = true
config.action_mailer.default_url_options = { host: "localhost", port: 3000 }

Mailbox n’utilise ni authentification SMTP ni TLS : omettez donc user_name, password et authentication. Avec raise_delivery_errors, un mauvais port provoque une erreur visible au lieu d’échouer en silence, et default_url_options fait pointer les liens de vos emails vers votre app locale.

Redémarrez le serveur Rails après avoir modifié les fichiers d’environnement.

3. Envoyez un email de test

Le plus rapide est d’envoyer un email ponctuel depuis le runner :

bin/rails runner 'ActionMailer::Base.mail(from: "app@example.com", to: "test@example.com", subject: "Hello from Rails", body: "It works!").deliver_now'

Déclenchez ensuite un vrai mailer — inscription, réinitialisation de mot de passe — et l’email arrive dans la même boîte de réception.

Exécuter Rails dans Docker

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

config.action_mailer.smtp_settings = { address: "host.docker.internal", port: 2525 }

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

  • Errno::ECONNREFUSED — le serveur Mailbox n’est pas démarré, ou le port ne correspond pas.
  • Rien n’arrive, sans erreur — les jobs deliver_later nécessitent un adaptateur de file d’attente actif (Solid Queue, Sidekiq…). Utilisez deliver_now pendant vos tests, ou lancez votre worker de jobs.
  • Les emails sont toujours journalisés dans la console — un autre fichier d’environnement ou un initializer surcharge delivery_method ; recherchez delivery_method dans le projet.

Que vérifier ensuite

Mailbox montre comment vos templates se comportent au-delà du navigateur : la vérification de compatibilité HTML signale le CSS qu’Outlook ou Gmail ignorent, et l’aperçu mobile affiche l’email dans un viewport de la taille d’un téléphone. Les aperçus de mailers (/rails/mailers) restent parfaits pour itérer sur un seul template ; Mailbox intercepte ce que votre app envoie réellement, de bout en bout.

Autres guides