WordPress email documentation from johnbillion/wp_mail
From the wildly prolific 
John Blackbourn, below is a clone of the johnbillion/wp_mail Github repo.
GitHub – johnbillion/wp_mail: Documentation for all the situations where WordPress core sends an email, how and when they happen, and how to filter or disable each one.
Documentation for all the situations where WordPress core sends an email, how and when they happen, and how to filter or disable each one. – GitHub – johnbillion/wp_mail: Documentation for all the situations where WordPress core sends an email, how and when they happen, and how to filter or disable each one.
This document lists all the situations where WordPress core sends an email, how and when they happen, and how to filter or disable each one.
This list was last updated for WordPress 6.7.
Table of Contents
- Information Applicable to All Emails
- Comments
- Change of Admin Email
- Change of User Email or Password
- Personal Data Requests
- Automatic Updates
- New User
- New Site
- Other
Information Applicable to All Emails
All emails sent by WordPress go through the pluggable wp_mail() function. The following general-purpose filters and actions are used in this function:
| Filters | wp_mailpre_wp_mailwp_mail_fromwp_mail_from_namewp_mail_content_typewp_mail_charset |
|---|---|
| Actions | phpmailer_initwp_mail_succeeded (WP 5.9+)wp_mail_failed |
Comments
Comment is awaiting moderation
Sent when a user or visitor submits a comment that gets held for moderation.
| To | - Site Admin - Post author, if they have the ability to edit the comment |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%1$s] Please moderate: "%2$s" |
| Function | wp_notify_moderator() |
| Pluggable | Yes |
| Filters | comment_moderation_recipientscomment_moderation_subjectcomment_moderation_textcomment_moderation_headers |
| Disable | - Return false from notify_moderator filter- Remove wp_new_comment_notify_moderator action from comment_post hook- "Email me whenever" settings on Settings -> Discussion screen - Overwrite the pluggable wp_notify_moderator() function |
Comment is published
Sent when:
- A user or visitor submits a comment that gets automatically approved
- A comment previously held for moderation gets approved.
| To | Post author |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%1$s] Comment: "%2$s" [%1$s] Pingback: "%2$s" [%1$s] Trackback: "%2$s" |
| Function | wp_notify_postauthor() |
| Pluggable | Yes |
| Filters | comment_notification_recipientscomment_notification_subjectcomment_notification_textcomment_notification_headers |
| Disable | - Return false from notify_post_author filter- Remove wp_new_comment_notify_postauthor action from comment_post hook- "Email me whenever" settings on Settings -> Discussion screen - Overwrite the pluggable wp_notify_postauthor() function- See also this hardcoded action added to wp_set_comment_status in wp_set_comment_status() |
Change of Admin Email
Change of site admin email address is attempted
Sent when a user attempts to change the Administration Email Address option on the General Settings screen.
| To | Proposed new email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] New Admin Email Address |
| Function | update_option_new_admin_email() |
| Pluggable | No |
| Filters | new_admin_email_subject (WP 6.5+)new_admin_email_content |
| Disable | Remove update_option_new_admin_email action from add_option_new_admin_email and update_option_new_admin_email hooks |
Site admin email address is changed
Sent when a user clicks the link in the email requesting confirmation of the change to the site admin email address (see above).
| To | Old site admin email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Admin Email Changed |
| Function | wp_site_admin_email_change_notification() |
| Pluggable | No |
| Filters | site_admin_email_change_email |
| Disable | Return false from send_site_admin_email_change_email filter |
Change of network admin email address is attempted
Multisite only. Sent when a user attempts to change the Network Admin Email option on the Network Settings screen.
| To | Proposed new email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Network Admin Email Change Request |
| Function | update_network_option_new_admin_email() |
| Pluggable | No |
| Filters | new_network_admin_email_content |
| Disable | Remove update_network_option_new_admin_email action from add_site_option_new_admin_email and update_site_option_new_admin_email hooks |
Network admin email address is changed
Multisite only. Sent when a user clicks the link in the email requesting confirmation of the change to the network admin email (see above).
| To | Old network admin email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Notice of Network Admin Email Change |
| Function | wp_network_admin_email_change_notification() |
| Pluggable | No |
| Filters | network_admin_email_change_email |
| Disable | Return false from send_network_admin_email_change_email filter |
Change of User Email or Password
User or Administrator requests a password reset
Sent when:
- A user clicks the "Lost your password?" link on the login screen and submits their email address
- An Administrator clicks the "Send password reset" link next to a user on the Users screen (WP 5.7+)
- An Administrator clicks the "Send Reset Link" from the user editing screen of another user (WP 5.7+)
| To | User |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Password Reset |
| Function | retrieve_password() |
| Pluggable | No |
| Filters | retrieve_password_titleretrieve_password_messageretrieve_password_notification_email (WP 6.0+) |
| Disable | - Return false from send_retrieve_password_email filter (WP 6.0+)- Return an empty message from retrieve_password_message filter |
User resets their password
Sent when a user resets their password after clicking the confirmation link sent by the "Lost your password?" feature (see above).
| To | Site admin |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Password Changed |
| Function | wp_password_change_notification() |
| Pluggable | Yes |
| Filters | wp_password_change_notification_email |
| Disable | - Remove wp_password_change_notification action from the after_password_reset hook- Overwrite the pluggable wp_password_change_notification() function |
User changes their password
Sent when a logged in user changes their password from the user profile screen.
| To | User |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Password Changed |
| Function | wp_update_user() |
| Pluggable | No |
| Filters | password_change_email |
| Disable | Return false from send_password_change_email filter |
User attempts to change their email address
Sent when a logged in user attempts to change their email address from the user profile screen.
| To | Proposed new email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Email Change Request |
| Function | send_confirmation_on_profile_email() |
| Pluggable | No |
| Filters | new_user_email_content |
| Disable | Remove send_confirmation_on_profile_email() action from personal_options_update hook |
User changes their email address
Sent when a user clicks the link in the email requesting confirmation of the change to their email address (see above).
| To | User |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Email Changed |
| Function | wp_update_user() |
| Pluggable | No |
| Filters | email_change_email |
| Disable | Return false from send_email_change_email filter |
Personal Data Requests
Personal data export or erasure request is created or resent
Sent when:
- A request is created or resent from the Tools -> Export Personal Data screen
- A request is created or resent from the Tools -> Erase Personal Data screen
| To | Requester email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%1$s] Confirm Action: %2$s |
| Function | wp_send_user_request() |
| Pluggable | No |
| Filters | user_request_action_email_subjectuser_request_action_email_contentuser_request_action_email_headers |
| Disable | Unknown, may have to remove the admin pages entirely by removing _wp_privacy_hook_requests_page action from admin_menu hook |
User confirms personal data export or erasure request
Sent when a user clicks the link in the personal data export or erasure request confirmation email (see above).
| To | - Site admin on a single site installation - Network admin on a Multisite installation |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%1$s] Action Confirmed: %2$s |
| Function | _wp_privacy_send_request_confirmation_notification() |
| Pluggable | No |
| Filters | user_request_confirmed_email_touser_request_confirmed_email_subjectuser_request_confirmed_email_content (WP 5.8+)user_request_confirmed_email_headersuser_confirmed_action_email_content (deprecated in 5.8) |
| Disable | Remove _wp_privacy_send_request_confirmation_notification() action from user_request_action_confirmed hook |
Site admin sends link to a personal data export
Sent when a site admin clicks the Send Export Link button next to a confirmed data export request.
| To | Requester email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Personal Data Export |
| Function | wp_privacy_send_personal_data_export_email() |
| Pluggable | No |
| Filters | wp_privacy_personal_data_email_towp_privacy_personal_data_email_subjectwp_privacy_personal_data_email_contentwp_privacy_personal_data_email_headers |
| Disable | Remove wp_privacy_send_personal_data_export_email() action from wp_privacy_personal_data_export_page hook |
Site admin erases personal data to fulfill a data erasure request
Sent when:
- An administrator clicks the Erase Personal Data button next to a confirmed data erasure request
- An administrator clicks the Force Erase Personal Data button next to a data erasure request of any status
| To | Requester email address |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Erasure Request Fulfilled |
| Function | _wp_privacy_send_erasure_fulfillment_notification() |
| Pluggable | No |
| Filters | user_erasure_fulfillment_email_touser_erasure_fulfillment_email_subject (WP 5.8+)user_erasure_fulfillment_email_content (WP 5.8+)user_erasure_fulfillment_email_headers (WP 5.8+)user_erasure_complete_email_subject (deprecated in 5.8)user_confirmed_action_email_content (deprecated in 5.8)user_erasure_complete_email_headers (deprecated in 5.8) |
| Disable | Remove _wp_privacy_send_erasure_fulfillment_notification() action from wp_privacy_personal_data_erased hook |
Automatic Updates
Automatic plugin or theme updates
Sent when a background automatic update to plugins and/or themes completes or fails.
| To | Site admin on a single site installation Network admin on a Multisite installation |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Some plugins and themes have automatically updated [%s] Some plugins were automatically updated [%s] Some themes were automatically updated [%s] Some plugins and themes have failed to update [%s] Some plugins have failed to update [%s] Some themes have failed to update |
| Function | WP_Automatic_Updater::after_plugin_theme_update() |
| Pluggable | No |
| Filters | auto_plugin_theme_update_email |
| Disable | - Return false from auto_plugin_update_send_email filter- Return false from auto_theme_update_send_email filter |
Automatic core update
Sent when a background automatic update to WordPress core completes or fails.
| To | Site admin on a single site installation Network admin on a Multisite installation |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%1$s] Your site has updated to WordPress %2$s [%1$s] WordPress %2$s is available. Please update! [%1$s] URGENT: Your site may be down due to a failed update |
| Function | WP_Automatic_Updater::send_email() |
| Pluggable | No |
| Filters | auto_core_update_email |
| Disable | - Return false from auto_core_update_send_email filter- Return false from send_core_update_notification_email filter |
Full log of background update results
Only sent when you are using a development version of WordPress and it's not under version control.
| To | Site admin on a single site installation Network admin on a Multisite installation |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Background Update Failed [%s] Background Update Finished |
| Function | WP_Automatic_Updater::send_debug_email() |
| Pluggable | No |
| Filters | auto_core_update_email |
| Disable | Return false from automatic_updates_send_debug_email filter |
New User
An existing user is invited to a site
Multisite only. Sent when an existing user is added to a site from Users -> Add New -> Add Existing User.
| To | User being invited |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Joining Confirmation |
| Function | wp-admin/user-new.php |
| Pluggable | No |
| Filters | invited_user_email |
| Disable | Click the "Skip Confirmation Email" checkbox when adding the user |
A new user is invited to join a site
Multisite only. Sent when a new user is invited to join a site from Users -> Add New -> Add New User.
| To | User being invited |
|---|---|
| From | [Network Name] <[network admin]> |
| Subject | [%1$s] Activate %2$s |
| Function | wpmu_signup_user_notification() |
| Pluggable | No |
| Filters | wpmu_signup_user_notification_subjectwpmu_signup_user_notification_email |
| Disable | - Click the "Skip Confirmation Email" checkbox when adding the user - Return false from wpmu_signup_user_notification filter |
| Note | There is a default filter attached to wpmu_signup_user_notification_email: admin_created_user_email() |
A new user account is created
Multisite only. Sent when a new user account is created via wpmu_create_user():
- From Network Admin -> Sites -> Add New and the email address doesn't already exist
- From Network Admin -> Sites -> [Edit] -> Users -> Add New User
- From Network Admin -> Users -> Add New
- From Users -> Add New -> Add New User and the "Skip Confirmation Email" checkbox is checked
- When a user activates their new account on
wp-activate.php - Via a REST API request to create a new user (
POSTto/wp/v2/users)
Details:
| To | Network Admin |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | New User Registration: %s |
| Function | newuser_notify_siteadmin() |
| Pluggable | No |
| Filters | newuser_notify_siteadmin |
| Disable | - Filter the registrationnotification option value- Remove action from the wpmu_new_user hook- Toggle "Registration notification" in Network Admin -> Settings |
A user is added, or their account activation is successful
Multisite only.
| To | User being added |
|---|---|
| From | [Network Name] <[network admin]> |
| Subject | New %1$s User: %2$s |
| Function | wpmu_welcome_user_notification() |
| Pluggable | No |
| Filters | update_welcome_user_subjectupdate_welcome_user_emailSee also the "Welcome User Email" setting in Network Admin -> Settings |
| Disable | - Click the "Skip Confirmation Email" checkbox when adding the user - Return false from the wpmu_welcome_user_notification filter- Remove action from the wpmu_activate_user hook |
A new user is created
When a new user is created, two emails are sent from the same function. One to the site admin:
| To | Site Admin |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] New User Registration |
| Filters | wp_new_user_notification_email_adminwp_send_new_user_notification_to_admin (WP 6.1+) |
and one to the newly created user:
| To | New user |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Login Details |
| Filters | wp_new_user_notification_emailwp_send_new_user_notification_to_user (WP 6.1+) |
Details:
| Function | wp_new_user_notification() |
|---|---|
| Pluggable | Yes |
| Disable | - Return false from the wp_send_new_user_notification_to_admin or wp_send_new_user_notification_to_user filter (WP 6.1+)- Remove wp_send_new_user_notifications() action from the register_new_user hook- Remove wp_send_new_user_notifications() action from the edit_user_created_user hook- Remove wp_send_new_user_notifications() action from the network_site_new_created_user hook- Remove wp_send_new_user_notifications() action from the network_site_users_created_user hook- Remove wp_send_new_user_notifications() action from the network_user_new_created_user hook- Overwrite the pluggable wp_new_user_notification() function |
New Site
A new site is created
Multisite only. Sent when a new site is created from Network Admin -> Sites -> Add New.
| To | Network Admin |
|---|---|
| From | Site Admin <[network admin]> |
| Subject | [%s] New Site Created |
| Function | wpmu_new_site_admin_notification() |
| Pluggable | No |
| Filters | new_site_email |
| Disable | Return false from the send_new_site_email filter |
User registers for a new site
Multisite only, with site registration allowed. Sent when a visitor registers a new user account and site from wp-signup.php.
| To | Site Admin |
|---|---|
| From | [Network Name] <[network admin]> |
| Subject | [%1$s] Activate %2$s |
| Function | wpmu_signup_blog_notification() |
| Pluggable | No |
| Filters | wpmu_signup_blog_notification_subjectwpmu_signup_blog_notification_email |
| Disable | - Return false from the wpmu_signup_blog_notification filter- Remove wpmu_signup_blog_notification() action from the after_signup_site hook |
User activates their new site, or site added from Network Admin -> Sites -> Add New
Multisite only.
| To | Network Admin |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | New Site Registration: %s |
| Function | newblog_notify_siteadmin() |
| Pluggable | No |
| Filters | newblog_notify_siteadmin |
| Disable | - Filter the registrationnotification option value- Change the "Registration notification" setting in Network Admin -> Settings - Remove newblog_notify_siteadmin() action from the wpmu_new_blog hook- Remove newblog_notify_siteadmin() action from the wp_initialize_site hook |
User activates their new site, or site added from Network Admin -> Sites -> Add New
Multisite only.
| To | New Site Admin |
|---|---|
| From | [Network Name] <[network admin]> |
| Subject | New %1$s Site: %2$s |
| Function | wpmu_welcome_notification() |
| Pluggable | No |
| Filters | update_welcome_subjectupdate_welcome_emailSee also the "Welcome Email" setting in Network Admin -> Settings |
| Disable | - Return false from the wpmu_welcome_notification filter- Remove wpmu_welcome_notification() action from the wpmu_activate_blog hook |
Other
Installation
Sent when WordPress is initially installed.
| To | Site Admin |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | New WordPress Site |
| Function | wp_new_blog_notification() |
| Pluggable | yes |
| Filters | wp_installed_email |
| Disable | Overwrite the pluggable wp_new_blog_notification() function |
A fatal error occurs
Sent when a fatal error occurs in a plugin or theme and Recovery Mode is not active.
Important: The wp_fatal_error_handler_enabled filter cannot be used by plugins as it runs too early. Information about using this filter can be found here.
| To | Site Admin / Value of RECOVERY_MODE_EMAIL constant |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Your Site is Experiencing a Technical Issue |
| Function | send_recovery_mode_email() |
| Pluggable | No |
| Filters | wp_fatal_error_handler_enabledrecovery_email_support_inforecovery_email_debug_inforecovery_mode_email |
| Disable | Define WP_DISABLE_FATAL_ERROR_HANDLER as trueReturn false from the wp_fatal_error_handler_enabled filter |
| Note | Does not currently apply to Multisite |
Site admin requests to delete site
Multisite only. Sent when an Administrator requests to delete their site from the Tools -> Delete Site screen.
| To | Site Admin |
|---|---|
| From | WordPress <wordpress@host> |
| Subject | [%s] Delete My Site |
| File | wp-admin/ms-delete-site.php |
| Pluggable | No |
| Filters | delete_site_email_content |
| Disable | Not possible |
License: GPLv2
Copyright 2015 - 2024 John Blackbourn
This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.