Test Rails emails locally on your Mac

Send every Action Mailer email from your Rails app to a local SMTP server on your Mac. Configure development.rb in a minute and inspect each email instantly.

Out of the box, Rails in development tries to deliver over SMTP and quietly ignores delivery errors, so you only see emails in the log — fine for a quick check, painful when you need to see the actual HTML. With Mailbox, Action Mailer delivers to a local SMTP server on your Mac and every email appears rendered, with headers, plain-text part and attachments. Nothing reaches a real inbox.

1. Start a server in Mailbox

Open Mailbox. On first launch it creates a server on port 2525 — make sure it’s started. If you add another server instead, Mailbox picks a free port for it; use that port in the steps below.

2. Configure Action Mailer

In 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 doesn’t use SMTP authentication or TLS, so leave out user_name, password and authentication. raise_delivery_errors makes a wrong port fail loudly instead of silently, and default_url_options makes links in your emails point at your local app.

Restart the Rails server after changing environment files.

3. Send a test email

The quickest check is a one-off mail from the runner:

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

Then trigger a real mailer — sign up, reset a password — and it lands in the same inbox.

Running Rails in Docker

Inside a container, 127.0.0.1 is the container itself. Point Action Mailer at your Mac instead:

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

If the container still can’t connect, turn on Allow Network Access in Mailbox (Settings → General) and restart the server, so it accepts connections from outside the loopback interface.

Troubleshooting

  • Errno::ECONNREFUSED — the Mailbox server isn’t running, or the port doesn’t match.
  • Nothing arrives, no error — deliver_later jobs need a running queue adapter (Solid Queue, Sidekiq…). Use deliver_now while testing, or run your job worker.
  • Still logging to the console — another environment file or an initializer overrides delivery_method; search the project for delivery_method.

What to check next

Mailbox shows how your templates hold up beyond the browser: the HTML compatibility check flags CSS that Outlook or Gmail ignore, and the mobile preview shows the email on a phone-sized viewport. Mailer previews (/rails/mailers) remain great for iterating on a single template; Mailbox catches what your app really sends end to end.

More guides