Test WordPress emails locally on your Mac

Catch every wp_mail() email from your local WordPress site, including WooCommerce and contact forms, with a local SMTP server on your Mac.

On a local WordPress site, emails usually vanish: wp_mail() hands them to PHP’s mail(), which on a Mac sends them nowhere useful. With Mailbox you route WordPress through SMTP to a server on your Mac, and every email — password resets, WooCommerce orders, contact form submissions — shows up fully rendered.

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. Send wp_mail() through SMTP

Create a must-use plugin at wp-content/mu-plugins/local-mailbox.php. Must-use plugins load automatically, and keeping this one out of version control means it never reaches production.

<?php
/**
 * Plugin Name: Local Mailbox SMTP
 * Description: Sends all wp_mail() email to Mailbox on this Mac. Development only.
 */

add_action('phpmailer_init', function ($phpmailer) {
    $phpmailer->isSMTP();
    $phpmailer->Host = '127.0.0.1';
    $phpmailer->Port = 2525;
    $phpmailer->SMTPAuth = false;
    $phpmailer->SMTPSecure = '';
    $phpmailer->SMTPAutoTLS = false;
});

// Sites on http://localhost send from "wordpress@localhost", which wp_mail() rejects.
add_filter('wp_mail_from', function ($from) {
    return is_email($from) ? $from : 'wordpress@example.test';
});

The first part routes mail through SMTP without authentication or TLS — Mailbox uses neither. The second fixes a quirk: by default WordPress sends from wordpress@ plus your site’s domain, and for a site at http://localhost:8080 that address has no dot in the domain, so wp_mail() refuses it before the email is even sent.

Prefer a plugin? An SMTP plugin such as WP Mail SMTP works too: choose the “Other SMTP” mailer, host 127.0.0.1, port 2525, encryption None and authentication off. On a localhost site, also set a From address with a real-looking domain.

3. Send a test email

With WP-CLI:

wp eval 'var_dump( wp_mail( "test@example.com", "Hello from WordPress", "It works!" ) );'

bool(true) means the email was handed over, and it appears in Mailbox. Or simply use Lost your password? on the login screen.

Local, DDEV and other Docker setups

If WordPress runs inside a container, 127.0.0.1 is the container itself. Use host.docker.internal as the host; if the connection is refused, turn on Allow Network Access in Mailbox (Settings → General) and restart the server. DDEV’s built-in Mailpit only catches PHP’s mail(), so once WordPress sends over SMTP, Mailbox receives the email instead. DDEV expects host services to listen on all interfaces, so turn on Allow Network Access there.

Troubleshooting

  • wp_mail() returns false — hook wp_mail_failed and log the error. Invalid address: (From) means the wp_mail_from filter is missing; otherwise it’s usually a stopped server or a wrong port.
  • Emails still don’t arrive — another SMTP plugin is overriding the settings. Disable it locally or point it at Mailbox.

What to check next

WooCommerce and theme emails are notoriously hard to get right across clients. Run the HTML compatibility check to see which CSS Outlook or Gmail won’t render, and use the mobile preview to check order emails on a phone-sized screen.

More guides