Development Workflow

Test PHP Email Delivery Locally with Mailpit

Capture outgoing development email in a local inbox so test messages cannot accidentally reach real recipients.

Email features are difficult to test safely when every development action sends a real message. A local mail-capture service accepts SMTP messages and displays them in a browser inbox without delivering them to external recipients.

Run a local mail catcher

Mailpit provides an SMTP endpoint and a web interface. It can be installed locally or run as a container. Record the SMTP host, port and web UI port from the configuration rather than assuming defaults, especially when another service already uses the port.

Point the PHP application to the test SMTP server

Configure the application's mail transport through environment variables. Use a local hostname or container service name appropriate to the runtime. Do not place production SMTP credentials in the development configuration. If the application uses Symfony Mailer or PHPMailer, configure the transport using that library's documented SMTP options.

Test meaningful scenarios

Send plain-text and HTML messages, attachments, password-reset links and notification templates. Inspect headers, sender identity, character encoding, URL generation and whether secrets or internal stack traces appear in the message. Test failure behavior when the SMTP service is unavailable.

Prevent accidental external delivery

Make the development environment fail closed if the local mail catcher is not reachable. Avoid automatic fallback to production SMTP. Use test-only recipient rewriting where appropriate and keep real customer addresses out of fixtures.

Understand the boundary

A captured message proves that the application generated and handed off an email to the local SMTP service. It does not prove that a production provider will accept the message, that DNS authentication is correct or that it will reach the inbox.

Further reading

Share this page Help other developers discover this resource.