Someone asks your WordPress site for a password reset. The login page tells them to check their email for the confirmation link. Nothing arrives. They look in spam, try again, and get the same message and the same empty inbox. Perhaps they give up; perhaps they find another way to contact you. Until they get in touch, nobody who could fix the problem has any reason to know there is one.
This is one way WordPress email fails that is especially hard to notice: the handoff succeeds, and the message never reaches its recipient. When wp_mail() returns true, WordPress is reporting on its own call, not on delivery. A test email that arrived once proves the day it was sent. nanoPost’s view is that knowing a site’s email works means checking, on a schedule, that messages arrive.
What “sent” means to WordPress
Core email uses wp_mail(), as do plugins that use WordPress’s mail API. In its default form it builds the message and hands it to PHPMailer, the email library bundled with WordPress, which passes it on to whatever does the actual sending. wp_mail() then returns true or false.
Normally, true means PHPMailer’s send step finished without throwing an error.
WordPress’s own source says as much. The action that fires on success, wp_mail_succeeded, carries this note in core: “The firing of this action does not necessarily mean that the recipient(s) received the email successfully. It only means that the send method above was able to process the request without any errors.”
What “without any errors” covers depends on where the message went next:
- PHP’s
mail()function, the default when no mailer plugin is installed. It hands the message to the server’s local mail system.
The PHP manual is blunt about the return value: mail()“Returns true if the mail was successfully accepted for delivery”, and “just because the mail was accepted for delivery, it does NOT mean the mail will actually reach the intended destination.” - An SMTP server, when a mailer plugin points WordPress at one. Success means the relay replied that it had accepted the message. Under
RFC 5321, a server that accepts a message takes on responsibility for delivering it, and if delivery later fails it must send a failure report, a bounce, to the message’s return address. That report arrives as a separate email, after wp_mail()has already returned. - A sending provider’s API, when a mailer plugin uses one. Each mailer plugin decides what counts as success here. Whatever it decides, the return value describes the request WordPress made, not what the receiving mailbox later did with the message.
There is one more path to true. Since WordPress 5.7, a plugin can answer for wp_mail() through the pre_wp_mail filter, and whatever it returns is what the caller sees. A plugin that queued mail for later could, in principle, return true once the message was stored; a plugin that switched email off could return true having sent nothing. Either would look exactly like a successful send to the code that asked.
Spam filtering and authentication checks at the receiving server, a full mailbox, a typo in the recipient’s address: any of these can stop the message after the sending server has accepted it. WordPress does not get that later result through the original wp_mail() return value; a separate bounce may be sent to the message’s return address instead.
Why nobody notices
A failure raised during the send can at least be observed: code that listens for the wp_mail_failed hook sees it. When the password reset email cannot be handed off, WordPress also shows the person asking for it an error that begins: “The email could not be sent. Your site may not be correctly configured to send emails.” That is an unhelpful message to receive, but it is a signal, and it gives the person something to report.
When the handoff succeeds and the message is lost afterwards, the person sees core’s default confirmation (in English: “Check your email for the confirmation link, then visit the login page.”) The site has done everything it knows how to do. wp_mail_failed does not fire, because nothing failed during the send.
The failure then lands on the worst-placed person to report it. A user who cannot get a password reset email is locked out of the site, and the way back in is the thing that is broken. A new account has the same problem: the new-user email carries the link the person uses to set a password, so a lost one leaves them with an account they cannot open. An administrator may go about routine work without ever meeting either failure. Order confirmations and form notifications can also be missed after a successful handoff. A locked-out user has to find some other way to reach the site before anyone hears about it.
The one mechanism email has for reporting a delivery failure after the fact, the bounce, does not necessarily help either. A bounce goes to the message’s envelope sender, the return address used by mail servers rather than the From address people see. In its default form, wp_mail() sets the From address but does not tell PHPMailer to use it as the envelope sender, so the envelope sender depends on how the site’s mail transport is configured. In nanoPost’s view, a bounce only helps if someone reads the mailbox it goes to, and nothing in WordPress makes sure anyone does.
It follows that the silence lasts until a bounce gets read or someone complains through a channel that does not depend on the broken one. nanoPost knows of no measurement of how long that takes, and the code path sets no time limit on it.
What checking actually takes
If a true from wp_mail() cannot confirm delivery, a single test email cannot confirm that email keeps working. That conclusion rests on how a site’s email is put together: it depends on its sending settings, its DNS records, its provider account and the receiving providers’ filtering, and any of them can change after the test without the test showing it.
nanoPost’s position is that a WordPress site’s email should be treated like its uptime: checked on a schedule, with the final answer coming from the receiving mailbox rather than from the code that claims success. In practice, that means three habits.
- Keep a record of what was handed off. An email log shows what WordPress tried to send, when, and whether the handoff failed. It answers “did WordPress try to send the reset email, and did the send raise an error?” The
wp_mail_failedhook explains what that record catches and what it cannot, and the email log plugin roundup compares the tools that keep one. - Send a test on a schedule, to a mailbox a person reads. A scheduled test can reveal a problem on the path to the tested mailbox that last month’s one-off test would miss. Treat the check as complete only when someone confirms the message arrived, and for most sites that is a manual step: a person who opens that mailbox and notices when the test message is missing. A mail rule that files the tests into one folder makes the gap easier to spot; it does not remove the need to look.
- Look at what happened after the handoff. Bounces, and any delivery records the sending service keeps, sit outside the original
wp_mail()call; delivery webhooks explains one way to bring them back to the site. Checking that WordPress can send emails walks through each layer, and an inbox placement test covers mail that arrives in spam.
None of this is complete coverage. A scheduled test checks delivery to one mailbox at one provider; a password reset to a customer at a different provider can still be filtered. The difference is that the site’s owner looks, on a schedule, instead of a locked-out user who may never report it. For a reader already chasing a missing reset email, users not receiving password reset emails is where to start.
Where Email Check fits
nanoPost makes a GPL-licensed WordPress plugin for the second habit. Email Check sends a test email with wp_mail() on a schedule, logs each result, and shows a notice in wp-admin when a check fails or when the scheduled checks stop running. It is ours, and it is not ranked in nanoPost’s plugin reviews or roundups.
It has the same limit. Email Check records what wp_mail() reports, so a pass is a successful wp_mail() result, not proof of delivery, and the test message still has to be looked for in the receiving mailbox. That last check is the one the site cannot make for you.

Leave a Reply