WordPress email subject update - phase 2

[ramiy]

WordPress send emails, using wp_mail() function, to inform the site admin when some important tasks are done and when it needs user confirmation.

In #37940 we standardized email subjects used by WordPress. We updated subject texts, added unified translation comments and added site title as a prefix to all the email subjects.

Now we should standardized the filters used to filter WordPress emails. Why? Because not all emails can be filtered.

I prefer to do this in two steps:

1. Separate the email subject from the wp_mail() function.
2. Add new filters to filter the email subject.

See the attached patches.

[ramiy]

This patch removed the email subject translation string from the wp_mail() functions into a separate $subject var.

I should mention that this conventions is used in other places in the code.

As a separate variable, we will be able to filter those email subjects.

[johnbillion]

Related:

• #42132
• #42133
• #42134
• #42135

Unofficial wp_mail() usage docs for reference: ​https://github.com/johnbillion/wp_mail

[ramiy]

@johnbillion Awesome job with the docs!

Let's try to promote the email tickets in 5.3 milestone.

[ramiy]

@johnbillion maybe 5.4 ?

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

[SirLouen]

I've been re-reviewing the current patch and the whole subjects list and I've found that most have been already been sorted during the past 6 years since this report was created.

These are the last remains. I've sent in a new patch, including the filters because it's a little extra effort to finally fulfill this requisite.

Although I have to say that the filters that have been deployed all over WP are extremely unorthodox, making it difficult to establish a common sense to hook to one or another (and forcing users to keep reviewing docs each single time one of those hooks wants to be used).

But things are how they are.

cc @johnbillion

[SirLouen]

Testing instructions

If you want to test, simply add these two filters
delete_site_email_subject
and
newblog_notify_siteadmin_subject

And for the return of the callback, use a text that will be the new subject

For testing, the first filter:

• Create a multisite WP
• Create a new site
• Then delete the site and check the incoming email. The subject will be your new subject in the filter.

For testing the other one.

• Enable site creation by users (Settings ⇾ Networks Settings ⇾ Allow new registrations ⇾ Logged-in users may register new sites)
• Create a new user and log with it.
• Go to /wp-signup.php
• Create a new site.

The check the incoming email. The subject must be the one you set in the filter.

[abcd95]

Test Report

Description

This report validates that the indicated patch works as expected, introducing new filters for various Multisite-related email subjects.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/9380

Environment

• WordPress: 6.9-alpha-60093-src
• PHP: 8.2.25
• Server: nginx/1.27.2
• Database: mysqli (Server: 8.4.4 / Client: mysqlnd 8.2.25)
• Browser: Chrome 139.0.0.0
• OS: macOS
• Theme: Twenty Twenty-Five 1.3
• MU Plugins: None activated
• Plugins:
  • Test Reports 1.2.0
  • WP Mail Logging 1.14.0

Actual Results

Without the patch: The filters do not exist.

With the patch applied:

✅ The new filter delete_site_email_subject works as expected when deleting a site from the network.

✅ The new filter newblog_notify_siteadmin_subject works as expected when a new site is created by a user.

✅ The new filter newuser_notify_siteadmin_subject works as expected when a new user registers on the network.

✅ The new filter new_user_email_subject works as expected when a user changes their email address from their profile.

Additional Notes

The following code was used to test the filters:

add_filter( 'delete_site_email_subject', function( $subject ) {
    return 'Hello World! - delete site';
} );

add_filter( 'newblog_notify_siteadmin_subject', function( $subject, $blog_id ) {
    return "Hello World! - new site";
}, 10, 2 );

add_filter( 'newuser_notify_siteadmin_subject', function( $subject, $user ) {
    return "Hello World! - new user";
}, 10, 2 );

add_filter( 'new_user_email_subject', function( $subject ) {
    return 'Hello World! - email change';
} );

Supplemental Artifacts

Delete Site -

New User -

New Site -

Email Change -

[pmbaldha]

Test Report

Description

This report confirms that the proposed patch functions as intended, adding new filters for several Multisite-related email subjects.

Patch tested: ​https://github.com/WordPress/wordpress-develop/pull/9380

Environment

• WordPress: 6.9-alpha-60093-src
• PHP: 8.2.29
• Server: nginx/1.29.1
• Database: mysqli (Server: 8.4.6 / Client: mysqlnd 8.2.29)
• Browser: Chrome 140.0.0.0
• OS: Windows 10/11
• Theme: Twenty Twenty-Five 1.3
• MU Plugins:
  • test.php
• Plugins:
  • Email Log 2.6
  • Test Reports 1.2.0

Actual Results

Without the patch:
The filters are not available.

With the patch applied:

✅ delete_site_email_subject — works as expected when deleting a site from the network.

✅ newblog_notify_siteadmin_subject — works as expected when a user creates a new site.

✅ newuser_notify_siteadmin_subject — works as expected when a new user registers on the network.

✅ new_user_email_subject — works as expected when a user updates their email address from their profile.

Additional Notes

The following code was used to test the filters:

<?php
add_filter( 'delete_site_email_subject', function( $subject ) {
    return 'Hello World! - delete site';
} );

add_filter( 'newblog_notify_siteadmin_subject', function( $subject, $blog_id ) {
    return "Hello World! - new site";
}, 10, 2 );

add_filter( 'newuser_notify_siteadmin_subject', function( $subject, $user ) {
    return "Hello World! - new user";
}, 10, 2 );

add_filter( 'new_user_email_subject', function( $subject ) {
    return 'Hello World! - email change';
} );

[wildworks]

The 6.9 Beta1 release will be released soon, but there has been no activity for over a month. I will change this ticket to feature-request.

[wildworks]

I will change this ticket to feature-request.

This was a mistake.

I will change the milestone on this ticket from 6.9 to Future Release.