Test Symfony emails locally on your Mac

Route every email from Symfony Mailer to a local SMTP server on your Mac with a single MAILER_DSN line, then inspect each message as it arrives.

Symfony Mailer is configured with a single DSN, which makes switching to a local catcher a one-line change. Point it at Mailbox and every email your Symfony app sends lands on your Mac — rendered HTML, plain text, headers and attachments — instead of in 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. Set the DSN

In .env.local (so it never reaches production):

MAILER_DSN=smtp://127.0.0.1:2525

Leave the user and password out of the DSN — Mailbox doesn’t use SMTP authentication or TLS. Clear the cache if you changed environment variables while the app was running:

php bin/console cache:clear

3. Send a test email

Symfony has a built-in command for this:

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

The message appears in Mailbox immediately. Emails from your controllers, Messenger handlers and notifiers take the same route.

Messenger and async emails

If Messenger routes SendEmailMessage to an async transport, emails are only sent when a worker consumes the queue:

php bin/console messenger:consume async

Running Symfony in Docker

Inside a container, 127.0.0.1 is the container itself. Use your Mac instead:

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

The Symfony Docker recipe also adds a Mailpit service called mailer to compose.override.yaml. When it’s there, the Symfony CLI exports its own MAILER_DSN from Docker, which wins over .env.local. Remove the service, or label it with com.symfony.server.service-ignore: true.

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

  • “Connection could not be established” — the Mailbox server isn’t running or the port is different.
  • The old DSN is still used — a real environment variable (including one exported by the Symfony CLI from Docker) takes precedence over .env.local; check with php bin/console debug:dotenv.
  • Nothing arrives, no error — the email is waiting in the Messenger queue; run a worker.

What to check next

Run Mailbox’s HTML compatibility check on your Twig email templates to spot CSS that Outlook or Gmail won’t render, and open the mobile preview to see them on a phone-sized screen.

More guides