Email Delivery

Core calls wp_mail() from about thirty places. The ones a site owner notices:

The messages are plain text by default, and every one passes through the same function and the same hooks, so a single must-use plugin configures delivery for all of them and for every plugin that calls wp_mail() too.

wp_mail( $to, $subject, $message, $headers, $attachments, $embeds ) lives in wp-includes/pluggable.php. It is a pluggable function: it is only defined if no plugin has defined wp_mail() first, which is how some delivery plugins replace it entirely. The sixth parameter, $embeds, arrived in 6.9 for inline images referenced as cid: URLs, with a wp_mail_embed_args filter for their Content-ID.

The steps, as WordPress 7.1.3 runs them:

true means only that the transport accepted the message. With mail() that is the local sendmail binary; with SMTP it is the first server. Neither says that the message reached an inbox. Bounces go to the envelope sender (Return-Path) and never come back to WordPress.

The PHPMailer library moved in 5.5 to wp-includes/PHPMailer/ under the PHPMailer\PHPMailer namespace. The old wp-includes/class-phpmailer.php and class-smtp.php files still exist only as deprecated shims that load the new classes and alias PHPMailer; code that requires them triggers a deprecation notice. The phpmailer_init hook receives the instance, so code should not instantiate PHPMailer itself.

The lumen-catalog plugin sends an HTML notice to the editors when a manuscript is submitted. Headers are passed as an array, one header per element:

Source: Code Reference: wp_mail()

Setting the content type per call through the header, as above, is safer than a global wp_mail_content_type filter: a filter left in place turns every core message (all written as plain text) into HTML with collapsed line breaks. User-supplied values that end up in headers must be sanitized, because a newline in a header value starts a new header.

The Advanced Administration Handbook is explicit that WordPress is neither a mail user agent nor a mail transfer agent (MTA): it wraps PHPMailer, and by default PHPMailer calls PHP’s mail(), which pipes the message to the binary in sendmail_path (default /usr/sbin/sendmail -t -i). Whether anything leaves the server is the host’s business. On a typical modern setup it fails for one of these reasons:

The handbook lists three ways out, in this order of preference for a self-managed server:

Managed WordPress hosts often provide their own relay or a mail plugin; their documentation comes first.

Lumen Press configures SMTP in a must-use plugin, so no administrator can deactivate it, and reads the connection details from constants or environment variables, so no credential is stored in the database or in Git. Locally the host is Mailpit; in production it is the relay of whichever transactional service the publisher contracts.

Source: Code Reference: phpmailer_init hook

The file goes in wp-content/mu-plugins/lumen-mail.php. The PHPMailer properties it sets:

From must be an address on a domain the relay is allowed to send for. Most providers reject a message whose From domain has not been verified in their console. In production, the values come from wp-config.php, which reads them from the environment or a secrets file mounted by the platform, never from the repository:

Source: Advanced Administration Handbook: wp-config.php

The plugin keeps Reply-To untouched: WordPress itself sets it only on comment notifications (to the commenter), and callers such as lumen_catalog_notify_submission() above pass their own. no-reply@ is a common sender, but a mailbox that a person reads gets better engagement and catches bounces and complaints that the provider forwards.

SMTP from PHP is synchronous. Each wp_mail() call opens a TLS connection, authenticates and sends, which adds hundreds of milliseconds to the request that triggers it (a comment submission, a password reset). For bulk mail, such as a newsletter, use a dedicated mailing service rather than a loop over wp_mail(); for many transactional messages, a local relaying MTA or a provider’s HTTP API plugin that queues sends is faster.

wp_mail() returns false on failure but core ignores the return value in almost every call, so a broken mail setup is silent unless something listens to wp_mail_failed. The WP_Error it receives has the PHPMailer message as its error message and the to, subject, message, headers, attachments and embeds of the failed message as error data, plus phpmailer_exception_code. The plugin above writes one line to the PHP error log, which is wp-content/debug.log when WP_DEBUG and WP_DEBUG_LOG are on, and otherwise the server’s error log (the container’s standard error in the official images). These are the messages observed on the test site:

Source: Code Reference: wp_mail_failed hook

The log line deliberately leaves out the message body: password reset and data-export emails contain secrets and personal data, and a log is the wrong place for them. For deeper SMTP debugging, $phpmailer->SMTPDebug = 2 in phpmailer_init prints the client-server dialogue (including AUTH exchanges, so only on a development copy), and $phpmailer->Debugoutput = 'error_log' sends it to the log instead of the response.

wp_mail_succeeded (5.9) receives the same data array after a successful send and is the place to count messages or record an audit trail. The authentication-failure row in the table above is the message defined in WP_PHPMailer and was not reproduced, because the local Mailpit accepts any login.

Receiving servers decide whether to trust a message from three DNS-published mechanisms. They are configured at the DNS provider and at the mail provider, not in WordPress; WordPress only has to send with a From address on the authenticated domain.

The records below are illustrative for the production domain lumenpress.example, with a fictitious provider host; they were not published or queried. A transactional service supplies the exact include: value and DKIM keys (often as CNAME records pointing at keys it rotates):

Source: Advanced Administration Handbook: Mail

Rules that cause most failures:

When the site sends through a local MTA or directly over SMTP without a provider’s signing, PHPMailer can add the DKIM signature itself in phpmailer_init. Lumen Press keeps the private key in a file mounted outside the web root:

Source: PHPMailer on GitHub

The key pair is generated once with OpenSSL; the public half, base64 without the PEM header lines, is the p= value of the selector’s TXT record:

Source: RFC 6376: DomainKeys Identified Mail (DKIM) Signatures

With the key mounted and LUMEN_DKIM_KEY_FILE defined, the message captured on the test site carried a header such as DKIM-Signature: v=1; d=lumenpress.example; s=lumen2026; a=rsa-sha256; c=relaxed/simple; .... The signature itself can only be verified once the public key is in DNS. After publishing real records, dig +short TXT _dmarc.<domain> and dig +short TXT <selector>._domainkey.<domain> confirm what receivers see, and the Authentication-Results header of a message received at a large mailbox provider shows spf=pass, dkim=pass and dmarc=pass.

A transactional email service is a provider that sends application-generated messages (resets, receipts, notifications) through its own reputable IP addresses, signs them with DKIM for the customer’s domain, processes bounces and complaints, and reports delivery events. Well-known providers include Amazon SES, Brevo, Mailgun, Mailjet, Postmark, SendGrid and SMTP2GO, and the mail services of Google Workspace and Microsoft 365 can relay low volumes too. This page does not recommend one; they differ in the points that matter to a WordPress site:

On the WordPress side there are two kinds of plugins. Generic SMTP plugins from the WordPress.org directory configure PHPMailer through phpmailer_init and store host and password in the database, usually with an option to read them from constants instead. Provider-specific plugins often replace the pluggable wp_mail() to call an HTTP API; only one plugin can define wp_mail(), so two of them conflict silently, and Site Health lists neither conflict. A short must-use plugin such as lumen-mail.php has no settings screen to misconfigure but needs a deployment to change.

Mailpit is a small SMTP server and web inbox for development: it accepts every message on port 1025, delivers nothing, and shows the messages at port 8025 together with a REST API for automated checks. Lumen Press adds it to the standard local stack from Local Development Environments with an override file, so the base compose.yaml stays unchanged:

Source: Mailpit documentation: Docker

Compose merges the environment maps of the two files, so the wordpress and cli services keep their database variables and gain the mail ones; lumen-mail.php is in the mu-plugins directory that the base file already mounts. COMPOSE_FILE saves repeating -f on every command:

Source: Mailpit documentation: API v1

The output on the test site (the message ID shortened, and the container names in the Received header replaced by <...>):

The Return-Path comes from Sender, and the HELO name (from lumenpress.test) and the Message-ID domain from Hostname in lumen-mail.php. The Text field of the reset message contains https://lumenpress.test/wp-login.php?login=admin&key=<key>&action=rp&wp_lang=en_US, so an end-to-end test can extract the link and complete the reset in a browser (see E2E Testing in the Browser). The submission notice from lumen_catalog_notify_submission() arrives with Content-Type: text/html; charset=UTF-8, the Reply-To of the author and the & in the admin link encoded as & by esc_url().

The special message ID latest returns the newest message; /api/v1/message/{ID}/headers returns parsed headers and /api/v1/message/{ID}/html-check scores the HTML for email-client compatibility. The web inbox at http://localhost:8025 shows the same messages for manual review.

Two interactions with other local setups:

The Administration Email Address (admin_email) in Settings > General receives most of the messages in the first table, so it should be a monitored shared mailbox (for example webmaster@lumenpress.example) rather than one person’s address. Changing it on the screen does not take effect until the link mailed to the new address is followed (since 4.9); the pending value waits in new_admin_email, which is why a site that cannot send mail can never change it from the screen. The message as captured by Mailpit:

The option storage and the WP-CLI commands that bypass the confirmation are covered in Settings Screens. The user’s own email address follows the same confirm-by-link rule on the profile screen, described in Users, Roles and Profiles.

Since 5.3, an administrator who logs in is also asked every six months to confirm that the admin email is still correct (the "Administration email verification" screen, wp-login.php?action=confirm_admin_email). The deadline is the admin_email_lifespan option; Remind me later postpones it by three days. Two filters change the intervals, and returning 0 from admin_email_check_interval turns the screen off, which suits sites where the address is managed by configuration:

Source: Code Reference: admin_email_check_interval filter

Fatal-error recovery links go to admin_email unless the RECOVERY_MODE_EMAIL constant in wp-config.php names another valid address, which is useful when the admin mailbox is on the same broken server. There is no constant for the admin email itself.