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.

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.