WordPress Email Documentation

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
• 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:

Comments

Comment is awaiting moderation

Sent when a user or visitor submits a comment that gets held for moderation.

Comment is published

Sent when:

• A user or visitor submits a comment that gets automatically approved
• A comment previously held for moderation gets approved.

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.

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

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.

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

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+)

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

User changes their password

Sent when a logged in user changes their password from the user profile screen.

User attempts to change their email address

Sent when a logged in user attempts to change their email address from the user profile screen.

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

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

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

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.

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

Automatic Updates

Automatic plugin or theme updates

Sent when a background automatic update to plugins and/or themes completes or fails.

Automatic core update

Sent when a background automatic update to WordPress core completes or fails.

Full log of background update results

Only sent when you are using a development version of WordPress and it's not under version control.

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.

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.

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:

A user is added, or their account activation is successful

Multisite only.

A new user is created

When a new user is created, two emails are sent from the same function. One to the site admin:

and one to the newly created user:

Details:

New Site

A new site is created

Multisite only. Sent when a new site is created from Network Admin -> Sites -> Add New.

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.

User activates their new site, or site added from Network Admin -> Sites -> Add New

Multisite only.

User activates their new site, or site added from Network Admin -> Sites -> Add New

Multisite only.

Other

Installation

Sent when WordPress is initially installed.

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.

Site admin requests to delete site

Multisite only. Sent when an Administrator requests to delete their site from the Tools -> Delete Site screen.

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.