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.
github.com

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.6.

Table of Contents

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_mail
pre_wp_mail
wp_mail_from
wp_mail_from_name
wp_mail_content_type
wp_mail_charset
Actions phpmailer_init
wp_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
FromWordPress <wordpress@host>
Subject[%1$s] Please moderate: "%2$s"
Functionwp_notify_moderator()
PluggableYes
Filters comment_moderation_recipients
comment_moderation_subject
comment_moderation_text
comment_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.
ToPost author
FromWordPress <wordpress@host>
Subject [%1$s] Comment: "%2$s"
[%1$s] Pingback: "%2$s"
[%1$s] Trackback: "%2$s"
Functionwp_notify_postauthor()
PluggableYes
Filters comment_notification_recipients
comment_notification_subject
comment_notification_text
comment_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.

ToProposed new email address
FromWordPress <wordpress@host>
Subject[%s] New Admin Email Address
Functionupdate_option_new_admin_email()
PluggableNo
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).

ToOld site admin email address
FromWordPress <wordpress@host>
Subject[%s] Admin Email Changed
Functionwp_site_admin_email_change_notification()
PluggableNo
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.

ToProposed new email address
FromWordPress <wordpress@host>
Subject[%s] Network Admin Email Change Request
Functionupdate_network_option_new_admin_email()
PluggableNo
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).

ToOld network admin email address
FromWordPress <wordpress@host>
Subject[%s] Notice of Network Admin Email Change
Functionwp_network_admin_email_change_notification()
PluggableNo
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+)
ToUser
FromWordPress <wordpress@host>
Subject[%s] Password Reset
Functionretrieve_password()
PluggableNo
Filters retrieve_password_title
retrieve_password_message
retrieve_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).

ToSite admin
FromWordPress <wordpress@host>
Subject[%s] Password Changed
Functionwp_password_change_notification()
PluggableYes
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.

ToUser
FromWordPress <wordpress@host>
Subject[%s] Password Changed
Functionwp_update_user()
PluggableNo
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.

ToProposed new email address
FromWordPress <wordpress@host>
Subject[%s] Email Change Request
Functionsend_confirmation_on_profile_email()
PluggableNo
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).

ToUser
FromWordPress <wordpress@host>
Subject[%s] Email Changed
Functionwp_update_user()
PluggableNo
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
ToRequester email address
FromWordPress <wordpress@host>
Subject[%1$s] Confirm Action: %2$s
Functionwp_send_user_request()
PluggableNo
Filters user_request_action_email_subject
user_request_action_email_content
user_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
FromWordPress <wordpress@host>
Subject[%1$s] Action Confirmed: %2$s
Function_wp_privacy_send_request_confirmation_notification()
PluggableNo
Filters user_request_confirmed_email_to
user_request_confirmed_email_subject
user_request_confirmed_email_content (WP 5.8+)
user_request_confirmed_email_headers
user_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.

ToRequester email address
FromWordPress <wordpress@host>
Subject[%s] Personal Data Export
Functionwp_privacy_send_personal_data_export_email()
PluggableNo
Filters wp_privacy_personal_data_email_to
wp_privacy_personal_data_email_subject
wp_privacy_personal_data_email_content
wp_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
ToRequester email address
FromWordPress <wordpress@host>
Subject[%s] Erasure Request Fulfilled
Function_wp_privacy_send_erasure_fulfillment_notification()
PluggableNo
Filters user_erasure_fulfillment_email_to
user_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.

ToSite admin on a single site installation
Network admin on a Multisite installation
FromWordPress <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
FunctionWP_Automatic_Updater::after_plugin_theme_update()
PluggableNo
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.

ToSite admin on a single site installation
Network admin on a Multisite installation
FromWordPress <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
FunctionWP_Automatic_Updater::send_email()
PluggableNo
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.

ToSite admin on a single site installation
Network admin on a Multisite installation
FromWordPress <wordpress@host>
Subject [%s] Background Update Failed
[%s] Background Update Finished
FunctionWP_Automatic_Updater::send_debug_email()
PluggableNo
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.

ToUser being invited
FromWordPress <wordpress@host>
Subject[%s] Joining Confirmation
Functionwp-admin/user-new.php
PluggableNo
Filters invited_user_email
DisableClick 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.

ToUser being invited
From[Network Name] <[network admin]>
Subject[%1$s] Activate %2$s
Functionwpmu_signup_user_notification()
PluggableNo
Filters wpmu_signup_user_notification_subject
wpmu_signup_user_notification_email
Disable - Click the "Skip Confirmation Email" checkbox when adding the user
- Return false from wpmu_signup_user_notification filter
NoteThere 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 (POST to /wp/v2/users)

Details:

ToNetwork Admin
FromWordPress <wordpress@host>
SubjectNew User Registration: %s
Functionnewuser_notify_siteadmin()
PluggableNo
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.

ToUser being added
From[Network Name] <[network admin]>
SubjectNew %1$s User: %2$s
Functionwpmu_welcome_user_notification()
PluggableNo
Filters update_welcome_user_subject
update_welcome_user_email
See 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:

ToSite Admin
FromWordPress <wordpress@host>
Subject[%s] New User Registration
Filters wp_new_user_notification_email_admin
wp_send_new_user_notification_to_admin (WP 6.1+)

and one to the newly created user:

ToNew user
FromWordPress <wordpress@host>
Subject[%s] Login Details
Filters wp_new_user_notification_email
wp_send_new_user_notification_to_user (WP 6.1+)

Details:

Functionwp_new_user_notification()
PluggableYes
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.

ToNetwork Admin
FromSite Admin <[network admin]>
Subject[%s] New Site Created
Functionwpmu_new_site_admin_notification()
PluggableNo
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.

ToSite Admin
From[Network Name] <[network admin]>
Subject[%1$s] Activate %2$s
Functionwpmu_signup_blog_notification()
PluggableNo
Filters wpmu_signup_blog_notification_subject
wpmu_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.

ToNetwork Admin
FromWordPress <wordpress@host>
SubjectNew Site Registration: %s
Functionnewblog_notify_siteadmin()
PluggableNo
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.

ToNew Site Admin
From[Network Name] <[network admin]>
SubjectNew %1$s Site: %2$s
Functionwpmu_welcome_notification()
PluggableNo
Filters update_welcome_subject
update_welcome_email
See 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.

ToSite Admin
FromWordPress <wordpress@host>
SubjectNew WordPress Site
Functionwp_new_blog_notification()
Pluggableyes
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.

ToSite Admin / Value of RECOVERY_MODE_EMAIL constant
FromWordPress <wordpress@host>
Subject[%s] Your Site is Experiencing a Technical Issue
Functionsend_recovery_mode_email()
PluggableNo
Filters wp_fatal_error_handler_enabled
recovery_email_support_info
recovery_email_debug_info
recovery_mode_email
Disable Define WP_DISABLE_FATAL_ERROR_HANDLER as true
Return 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.

ToSite Admin
FromWordPress <wordpress@host>
Subject[%s] Delete My Site
Filewp-admin/ms-delete-site.php
PluggableNo
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.