How to customize wordpress user emails

Why customize core wordpress user email messages?

By default emails sent out to users when they register, reset there password, update their profile or request a new password are not tailored to fit your website or blog.

For example you could send out helpful information to newly registered users about their account and benefits that come with their current membership, allowing you to send out different emails tailored to each user level.

Or if you want to modify the wordpress password changed email to include some best practices to keep their account secure.

WordPress new user notification email

The new user notification email is sent to wordpress user when they first register an account on your website, this email by default sends a link to activate the user account by redirecting the user to the reset password form.

The default WordPress new user notification email message looks like the following:

Username: newuser1@example.co.uk

To set your password, visit the following address:

https://localhost/wp-login.php?action=rp&key=gsxGKwZLHPHpRPXUlJDx&login=asd

https://localhost/wp-login.php

The new user notification email message can be customized using the wp_new_user_notification_email filter, allowing you to change the new user notification email message and subject by returning a modified array.

The following snippet shows how the default message is generated allowing it to be customized as required, we use the get_password_rest_key function to get the user activation key and append it to the activation url.

function jc_cwue_new_user_notification_email($wp_new_user_notification_email, $user, $blogname)
{
    $key = get_password_reset_key($user);

    // Default Email message
    $message  = sprintf(__('Username: %s'), $user->user_login) . "\r\n\r\n";
    $message .= __('To set your password, visit the following address:') . "\r\n\r\n";
    $message .= network_site_url("wp-login.php?action=rp&key=$key&login=" . rawurlencode($user->user_login), 'login') . "\r\n\r\n";
    $message .= wp_login_url() . "\r\n";

    $wp_new_user_notification_email['subject'] =  __('[%s] Login Details');
    $wp_new_user_notification_email['message'] = $message;

    return $wp_new_user_notification_email;
}

add_filter('wp_new_user_notification_email', 'jc_cwue_new_user_notification_email', 10, 3);

WordPress password changed email

The WordPress password change email is sent to the user as the name suggests when their password is changed via the edit profile form, the email is an alert to allow the user to take action if this was not an authorized password change.

The default WordPress password changed email message contents:

Hi asd,

This notice confirms that your password was changed on dev.

If you did not change your password, please contact the Site Administrator at
admin@example.co.uk

This email has been sent to newuser1@example.co.uk

Regards,
All at dev
https://localhost

Customizing the WordPress password changed email message is done using the password_change_email filter, allowing you to change details of the email by modifying the message or subject keys and returning the modified array.

The following snippet shows how the default password changed email message and subject are created, using the replacement strings to insert user and site specific content.

function jc_cwue_password_change_email($pass_change_email, $user, $userdata)
{
    $pass_change_email['message'] =  __(
        'Hi ###USERNAME###,

This notice confirms that your password was changed on ###SITENAME###.

If you did not change your password, please contact the Site Administrator at
###ADMIN_EMAIL###

This email has been sent to ###EMAIL###

Regards,
All at ###SITENAME###
###SITEURL###'
    );

    $pass_change_email['subject'] = __('[%s] Password Changed');

    return $pass_change_email;
}

add_filter('password_change_email', 'jc_cwue_password_change_email', 10, 3);

A full list of default WordPress replacement strings that will automatically be replaced in the email message with their dynamic values:

###USERNAME###    The current user's username.
###ADMIN_EMAIL### The admin email in case this was unexpected.
###EMAIL###       The user's email address.
###SITENAME###    The name of the site.
###SITEURL###     The URL to the site.

WordPress retrieve password email

The WordPress retrieve password email is sent to a user to providing them with a link to set a new password, this email is normally generated from the forgotten password page or via the wordpress admin users list where it can also be triggered.

The default WordPress retrieve password email contents:

Someone has requested a password reset for the following account:

Site Name: dev

Username: asd

If this was a mistake, ignore this email and nothing will happen.

To reset your password, visit the following address:

https://localhost/wp-login.php?action=rp&key=irRqMfoVCAsPVnDyQ1a4&login=asd&wp_lang=en_US

This password reset request originated from the IP address x.x.x.x.

Customizing the WordPress retrieve password email can be done using two wordpress filters, the retrieve_password_title filter is used to modify the email subject text, retrieve_password_message filter is used to modify the retrieve password email message.

The following code snippets consist of a helper function to get the sites name, and two functions to modify the subject and email content showing how the defaults are generated.

function jc_cwue_get_site_name()
{
    if (is_multisite()) {
        $site_name = get_network()->site_name;
    } else {
        /*
		 * The blogname option is escaped with esc_html on the way into the database
		 * in sanitize_option. We want to reverse this for the plain text arena of emails.
		 */
        $site_name = wp_specialchars_decode(get_option('blogname'), ENT_QUOTES);
    }

    return $site_name;
}

function jc_cwue_retrieve_password_subject($subject, $user_login, $user_data)
{

    $site_name = jc_cwue_get_site_name();
    $subject = sprintf(__('[%s] Password Reset'), $site_name);

    return $subject;
}

add_filter('retrieve_password_title', 'jc_cwue_retrieve_password_subject', 10, 3);

function jc_cwue_retrieve_password_message($message, $key, $user_login, $user_data)
{
    // Localize password reset message content for user.
    $locale = get_user_locale($user_data);

    $site_name = jc_cwue_get_site_name();

    $message = __('Someone has requested a password reset for the following account:') . "\r\n\r\n";
    /* translators: %s: Site name. */
    $message .= sprintf(__('Site Name: %s'), $site_name) . "\r\n\r\n";
    /* translators: %s: User login. */
    $message .= sprintf(__('Username: %s'), $user_login) . "\r\n\r\n";
    $message .= __('If this was a mistake, ignore this email and nothing will happen.') . "\r\n\r\n";
    $message .= __('To reset your password, visit the following address:') . "\r\n\r\n";
    $message .= network_site_url("wp-login.php?action=rp&key=$key&login=" . rawurlencode($user_login), 'login') . '&wp_lang=' . $locale . "\r\n\r\n";

    if (!is_user_logged_in()) {
        $requester_ip = $_SERVER['REMOTE_ADDR'];
        if ($requester_ip) {
            $message .= sprintf(
                /* translators: %s: IP address of password reset requester. */
                __('This password reset request originated from the IP address %s.'),
                $requester_ip
            ) . "\r\n";
        }
    }

    return $message;
}
add_filter('retrieve_password_message', 'jc_cwue_retrieve_password_message', 10, 4);

WordPress email address change request message

The WordPress email address change request email is sent to the users new email address to verify it, this email is normally generated via the edit profile form.

The default WordPress email change request message:

Howdy asd,

You recently requested to have the email address on your account changed.

If this is correct, please click on the following link to change it:
https://localhost/wp-admin/profile.php?newuseremail=be8c2e9eacc5198bd7df059ce37f9d84

You can safely ignore and delete this email if you do not want to
take this action.

This email has been sent to asdasd@asd.com

Regards,
All at dev
https://localhost

Customizing the WordPress email address change request email is done using the new_user_email_content filter, this filter allows you to change the email body text and allows you to use the following placeholders that will be replaced with the dynamically content before being sent.

function jc_cwue_new_user_email_content($email_text, $new_user_email)
{

    $email_text = __(
        'Howdy ###USERNAME###,

You recently requested to have the email address on your account changed.

If this is correct, please click on the following link to change it:
###ADMIN_URL###

You can safely ignore and delete this email if you do not want to
take this action.

This email has been sent to ###EMAIL###

Regards,
All at ###SITENAME###
###SITEURL###'
    );

    return $email_text;
}
add_filter('new_user_email_content', 'jc_cwue_new_user_email_content', 10, 2);

Dynamic value placeholders:

###USERNAME###    The current user's username.
###ADMIN_EMAIL### The admin email in case this was unexpected.
###EMAIL###       The user's email address.
###SITENAME###    The name of the site.
###SITEURL###     The URL to the site.

WordPress email address changed message

The WordPress email address changed email is sent to the users current email address when a user updates their email address, this email is generated via the edit profile form and is used to alert a user to any unauthorized attempt of change of email.

The default WordPress email changed message:

Hi asd,

This notice confirms that your email address on dev was changed to asdasd@asd.com.

If you did not change your email, please contact the Site Administrator at
test@test.com

This email has been sent to asd@asd.com

Regards,
All at dev
https://localhost

Customizing the WordPress email address changed email is done by using the email_change_email filter, this filter allows you override the email subject or message by replacing the returned array data, the email message allows you to enter placeholders that will be changed to show the correct dynamic value before the email is sent.

function jc_cwue_email_change_email($email_change_email, $user, $userdata)
{
    $email_change_email['subject'] = __('[%s] Email Changed');

    $email_change_email['message'] = __(
        'Hi ###USERNAME###,

This notice confirms that your email address on ###SITENAME### was changed to ###NEW_EMAIL###.

If you did not change your email, please contact the Site Administrator at
###ADMIN_EMAIL###

This email has been sent to ###EMAIL###

Regards,
All at ###SITENAME###
###SITEURL###'
    );

    return $email_change_email;
}
add_filter('email_change_email', 'jc_cwue_email_change_email', 10, 3);

Dynamic value placeholders:

###USERNAME###    The current user's username.
###ADMIN_EMAIL### The admin email in case this was unexpected.
###NEW_EMAIL###   The new email address.
###EMAIL###       The old email address.
###SITENAME###    The name of the site.
###SITEURL###     The URL to the site.