Site Health: Add recurring email delivery checks

[wpxhouston]

Adds an administrator-initiated email delivery check directly to Site Health.

WordPress installations frequently depend on server mail configuration for password resets, user notifications, and administration messages, but a successful wp_mail() call does not prove inbox delivery. This change asks administrators to periodically perform and manually confirm a delivery test without adding mail service credentials to Core.

The change:

• adds a recommended Site Health test when delivery has never been tested or the last successful send request is more than 90 days old;
• adds a Verify email delivery action to the Site Health test for both recommended and passed states;
• sends the test to the email address of the user initiating it;
• clearly asks the user to confirm inbox receipt and inspect sender headers;
• stores a non-autoloaded, site-wide record containing the timestamp and tested recipient identity only when WordPress hands the message to the mail system without an immediate error;
• invalidates that record if the tested user is deleted or their email address changes; and
• uses Core's existing Site Health scoring, filtering, and cached issue-count behavior.

The UI explicitly notes that accepting the message for sending does not guarantee delivery.

Trac ticket: https://core.trac.wordpress.org/ticket/65891

Testing

• php -l src/wp-admin/includes/class-wp-site-health.php
• php -l src/wp-admin/site-health.php
• php -l tests/phpunit/tests/admin/wpSiteHealth.php
• ./vendor/bin/phpcs --standard=phpcs.xml.dist src/wp-admin/includes/class-wp-site-health.php src/wp-admin/site-health.php tests/phpunit/tests/admin/wpSiteHealth.php
• ./vendor/bin/phpcs --standard=phpcompat.xml.dist src/wp-admin/includes/class-wp-site-health.php src/wp-admin/site-health.php tests/phpunit/tests/admin/wpSiteHealth.php
• ./vendor/bin/phpstan analyse --memory-limit=2G src/wp-admin/includes/class-wp-site-health.php src/wp-admin/site-health.php --no-progress
• npx grunt jshint:core
• git diff --check

New PHPUnit coverage is included for missing, malformed, future, expired, and current records; successful and failed send requests; missing user addresses; non-autoloaded structured storage; changed and deleted recipients; site-wide validity for other administrators; and Site Health test registration. PHPUnit was not run locally because this host does not have an isolated Core test database; GitHub Actions provides the isolated test matrix.

Use of AI Tools

AI assistance: Yes
Tool(s): OpenAI Codex
Model(s): GPT-5
Used for: Implementing and reviewing the change, generating tests, adapting the prototype to current trunk, addressing review feedback, and running local validation.

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props wpspin, jorbin, clorith.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Copilot]

Pull request overview

Adds recurring administrator email-delivery checks through Site Health and General Settings.

Changes:

• Adds email test sending, timestamp tracking, and Site Health reporting.
• Adds General Settings controls and result notices.
• Adds dashboard status handling and PHPUnit coverage.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
class-wp-site-health.php	Implements delivery checks and Site Health integration.
options-general.php	Adds the verification UI and notices.
site-health.js	Forces overdue checks to show improvement needed.
wpSiteHealth.php	Tests timestamps, sending, and registration.

Suppressed comments (1)

src/wp-admin/includes/class-wp-site-health.php:207

• This unconditional override bypasses Site Health's filtering contract. A plugin can remove email_delivery through the documented site_status_tests filter (or filter its result to good), but an overdue timestamp still forces the UI to “Should be improved” even though the effective test set contains no recommendation. Derive the override from the filtered/effective result rather than directly from the option.

				'force_improvable' => ! $this->is_email_delivery_test_current(),

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[aaronjorbin]

Thank you for starting on this, I think it could be a good addition. A couple of initial thoughts, both big picture and specific (inline for those)

1. Change it so that it sends the email to the current user. I think this would be helpful since the user who is testing it may not have access to the admin email.
2. I think that it would be best to keep it all under site health rather than redirecting to the setting screen.
3. I think it could make sense to also include similar functionality, but that is focused on the admin email, on the confirm admin screen

[aaronjorbin]

cc/ @Clorith due to the work you did on site health

[wpxhouston]

Thanks for the feedback. I have switched the recipient to the current user and moved the complete workflow into Site Health. The administration-email confirmation screen is a useful idea, but I think it should remain separate follow-up scope.

[Clorith]

I had the completely opposite approach to your thought here @aaronjorbin , I would've said that individual user tests aren't as valuable as ensuring deliverability (and access to) the admin email configured on a site, and I would have the check be specifically for that since that covers both that emails work, and that the address they've confirmed is correct is one they can also access then.

I do like the intention behind the idea, let's dive into some initial thoughts I had when looking it over and narrow down some questions, as there are some things I suggest we consider, and have answers to;

A test you're required to make every X days feels a little burdensome on site admins, granted purposes and priorities shift, the initial idea was that checks ran in the background and only required user interaction when something failed, and even then it had clear actions for users of all technical levels.

At the same time, 90 days may not be often enough, the tricky thing about email is that it can change at a whim, your server is blocked one day, your domain ends up on some obscure blocklist the other, different mail-services use different blocklists, how do we account for this to make the test reliable?

Finally, we also need to account for the health checks being reset on every core update (intentionally, as changes in core may have changed the results of your tests on your environment), is this an acceptable level of recurrence?