Disclosure first: I run Envbay, a small hosted service for Envoryx. The first half of this works with plain Docker and nothing of mine.

Everybody knows one of these stories. A staging copy of a shop, a real customer table in the database, a cron job nobody switched off, and on Sunday a few dozen people get "your order has shipped" for an order that doesn't exist.

The fix is boring: give every dev and staging setup a catch-all inbox before it gets anything else. I use Mailpit for that. It speaks SMTP on one port, shows a web inbox on another, and delivers nothing to anyone.

Everything below I ran myself before writing it down, with Mailpit 1.33, Laravel 13, Symfony 8.1 and WordPress 7.1.

The plain version

docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit 

SMTP is on 1025, the inbox is on http://localhost:8025. No user, no password, no TLS. That's the point.

Laravel

MAIL_MAILER=smtp MAIL_HOST=127.0.0.1 MAIL_PORT=1025 

A fresh Laravel ships with MAIL_MAILER=log and port 2525, so these three lines are the ones to change. Older tutorials add MAIL_ENCRYPTION=null. Current Laravel doesn't read that any more (the setting is MAIL_SCHEME now), and Mailpit doesn't need it.

Then send something without clicking through your app:

php artisan tinker --execute="Mail::raw('hello', fn (\$m) => \$m->to('test@example.com')->subject('Mailpit test'));" 

If Mailpit runs as a container next to your app, MAIL_HOST is the container name instead of 127.0.0.1.

Symfony

MAILER_DSN=smtp://localhost:1025 
php bin/console mailer:test test@example.com 

The command prints nothing when it works. The mail arrives with the subject "Testing transport". One trap: with the recipe default MAILER_DSN=null://null the command is just as quiet and just as successful, it only doesn't send anything. Look in the inbox, not at the exit code.

WordPress

WordPress is the awkward one because wp_mail() hands everything to PHP's mail() unless told otherwise. In the official Docker image there is no sendmail, so out of the box you get "Could not instantiate mail function" and false. Two ways to deal with it.

Either point PHPMailer at Mailpit with a tiny must-use plugin, wp-content/mu-plugins/mailpit.php:

<?php add_action('phpmailer_init', function ($phpmailer) { $phpmailer->isSMTP(); $phpmailer->Host = 'mailpit'; $phpmailer->Port = 1025; $phpmailer->SMTPAuth = false; }); 

Or make mail() itself go there. Install msmtp in the PHP container and put this in a php.ini snippet:

sendmail_path = "msmtp -t --host=mailpit --port=1025 --from=dev@example.test" 

The --from is not optional, msmtp refuses to send without a sender. The second way also catches old plugins and hand-written PHP that never heard of SMTP, which is why I prefer it.

One thing to know: WordPress builds its sender as wordpress@ plus the site's domain. On a site whose URL is a bare http://localhost, wp_mail() fails with "Invalid address" whatever you configure. Give the site a hostname with a dot in it.

Two ways mail still gets out

HTTP APIs. If the app sends through the API of Mailgun, Postmark or SES, that's an HTTPS call. It never touches SMTP and Mailpit never sees it. On staging, switch the mailer to smtp or log.

The one setting you forgot. A plugin with its own SMTP credentials, a second mailer in config/mail.php, a script that calls an external relay directly. You won't find all of them by reading config. A second safeguard helps: block outgoing ports 25, 465 and 587 on the machine. Then a forgotten setting fails loudly instead of delivering quietly.

One more thing that surprises people: by default Mailpit keeps mail in a temporary database that is thrown away when it stops. Restart the container and the inbox is empty. For test mail that's fine, just don't go looking for yesterday's password reset.

The same thing in Envoryx

I do my dev and staging setups in Envoryx, an open-source tool where every project gets its own containers and address. There Mailpit is a checkbox in the project wizard, or you add it later on the project's Services tab.

What I got for the checkbox when I tested it:

  • The app gets MAIL_MAILER=smtp, MAIL_HOST=mailpit, MAIL_PORT=1025 as environment variables, plus MAILER_DSN=smtp://mailpit:1025 for Symfony. The Laravel one-liner and mailer:test from above worked in fresh template projects without touching .env.
  • sendmail_path is already set to msmtp pointing at Mailpit. wp_mail() returned true on a fresh WordPress and the mail was in the inbox. No plugin.
  • The inbox gets its own address, https://<project>-mailpit.<your base domain>. From outside, without being signed in to the instance, it answers 401.
  • Restarting the project emptied the inbox there too.
  • Without Mailpit in the project there is no sendmail at all, and mail() returns false.

If you'd rather not run the server

That's what Envbay is: your own Envoryx instance, hosted, dev and staging only, servers in the EU, in beta. Outgoing mail ports are closed there for exactly the reason above. There's a free 7-day plan if you want to try the checkbox: envbay.com.

How do you keep staging from talking to real people? If there's a hole I haven't thought of, tell me in the comments.