Skip to main content

Debugging Emails with MailCatcher

Learn how to safely test and inspect outgoing WordPress emails in Seravo's local Docker development environment using the built-in MailCatcher tool.

MailCatcher is a built-in tool in Seravo's local Docker development environment that simulates a real mail server. It intercepts all outgoing emails sent by PHP and WordPress in your local environment, reports to WordPress that the message was delivered successfully, and stores the emails for inspection in your browser. Inside the development container, MailCatcher runs as a local SMTP server on port 1025, to which PHP's mail() function is pre-routed.

This allows you to safely test WooCommerce order confirmations, password reset emails, and contact form submissions without any risk of sending test messages to real customers or users.

mailcatcher in Vagrant

The image shows an example of the MailCatcher user interface.

Opening MailCatcher in Your Browser

MailCatcher starts automatically whenever you launch the local development environment (seravo-docker up). You can view intercepted emails in your browser at either of the following URLs:

  • http://<site>.local/.seravo/mailcatcher/ (default: http://wordpress.local/.seravo/mailcatcher/)

  • http://mailcatcher.<site>.local/ (default: http://mailcatcher.wordpress.local/)

In the web interface, each captured email can be inspected in three formats:

  • HTML: Displays the visual layout as rendered by standard email clients.

  • Plain Text: Displays the plain-text fallback version without HTML formatting.

  • Source: Displays the raw message source and email headers (such as From, To, Reply-To, Subject, and MIME structure) for detailed troubleshooting.

Testing Outgoing Emails

You can test email delivery either by triggering standard WordPress actions (such as a password reset or contact form submission) or by sending a test email directly from the development container's command line (seravo-docker ssh):

# Send a test email using Seravo's built-in utility
wp-mail-test [email protected]

# Or test WordPress's wp_mail() function directly via WP-CLI
wp eval 'wp_mail( "[email protected]", "Test Subject", "Test email body" );'

The sent message appears immediately in the MailCatcher web interface.

External SMTP Plugins and Email Services

By default, MailCatcher captures all emails sent through the server's local PHP mail() function—the standard delivery method used by WordPress's wp_mail() in Seravo's environment.

Warning: MailCatcher does not intercept traffic if your site uses a third-party SMTP plugin (which connects directly to an external SMTP server on ports 587 or 465) or an API-based email service (such as Mailchimp, SendGrid API, or Brevo). When pulling a production database into your local environment (wp-pull-production-db), deactivate external SMTP plugins during development using wp plugin deactivate <plugin-slug> to prevent test emails from reaching real recipients.

Common Issues and Troubleshooting

  • The MailCatcher URL does not load or returns a 502 Bad Gateway error: Ensure the local Docker environment is running (seravo-docker up) and that your local DNS resolver routes .local domains to 127.0.0.1.

  • Emails do not appear in MailCatcher: First verify basic delivery by running wp-mail-test [email protected] inside the container. If the test email appears in MailCatcher but WordPress forms fail to send messages, check active plugins (wp plugin list) for an external SMTP plugin or inspect the PHP error log (/data/log/php-error.log).

  • Test emails were delivered to real email addresses: Your site likely has an active external SMTP plugin or API integration inherited from the production database that bypasses local mail routing. Deactivate the plugin in your local development environment.

See Also

MailCatcher helps ensure that email templates, form notifications, and e-commerce receipts work reliably before deploying changes to production. If you need assistance with local development tools or email troubleshooting, our support team is happy to help at [email protected].

Did this answer your question?