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_laterjobs need a running queue adapter (Solid Queue, Sidekiq…). Usedeliver_nowwhile testing, or run your job worker. - Still logging to the console — another environment file or an initializer overrides
delivery_method; search the project fordelivery_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.