How To Edit The New User Email Template In WordPress

I was working on building out a theme for a WordPress site that is essentially a marketplace for services. We had two types of people signing up: hirers and job seekers. The default initial email was fine for hirers, but we found a lot of the job seekers were signing up and not completing their profile, which meant they'd never show up in the on-site search and never be hired.

All we needed was to tack on an extra paragraph to the first email for a certain type of user.

None of the plugins could handle the detail we needed. All the guides were for replacing the email message with a custom message. The problem with that is it's a lot more coding to get that individual password generation url that WordPress does by default.

The Solution

So how did we edit the new user email template in WordPress?

• Add a filter to hook into wp_new_user_notification_email which takes 3 arguments
• Pass $wp_new_user_notification_email, $user, $blogname into the filter
• Conditionally add $wp_new_user_notification_email['message'] .= sprintf("\r\nMessage Addition");
• Return $wp_new_user_notification_email

Let's see how that actually worked in the code...

/* Customize Emails */
add_filter('wp_new_user_notification_email', 'rego_welcome_email', 10, 3);

function rego_welcome_email($wp_new_user_notification_email, $user, $blogname)
{
  if (get_user_meta($user->ID, 'membership_user_role', true) == 'job_seeker')
  {
    # change the default email
    $wp_new_user_notification_email['message'] .= sprintf("\r\nWhile you're there,
      please complete your profile, so that potential hirers can find you and
      contact you.\r\n\r\nSee you there,\r\nWebsite Owner");
  }
  return $wp_new_user_notification_email;
}

Unpacking The Code

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

This is a filter, rather than a hook. It means we're overlaying our own information, while preserving anything we don't overwrite.

Notice the "10, 3" at the end? The 10 is the priority of the filter and 3 is how many arguments are passing through to the function. Leave them as written. Just remember that you have to have 3 arguments in the function.

function rego_welcome_email($wp_new_user_notification_email, $user, $blogname) {}

Even though we're not using $blogname, we still need to pass it in, because the filter told the function to expect 3 arguments. Your code will throw an error if you don't have 3 arguments here.

With PHP, the names of the arguments here don't matter (except for code readability). The information will be passed to your function in that order, no matter what you call it. It's best to stick with standard naming conventions where possible.

if (get_user_meta($user->ID, 'membership_user_role', true) == 'job_seeker') {}

At another place, earlier in the process, our code assigns "job_seeker" as a user_meta for job seekers. This allowed us to only send this email addition to job seekers, rather than to everyone. If you wanted to send the addition to everyone, you'd just leave out this conditional.

$wp_new_user_notification_email['message'] .= sprintf("\r\nMessage Addition");

$wp_new_user_notification_email is passed as an associative array. The ['message'] means this will only affect the body of the email. See below for the code to change the Subject.

The ".=" means we're adding to the end of the email message. If you wanted to replace the body of the message, you'd just do "=" without the full stop.

If you wanted to add your message to the start of the email, you'd do something like this:

Note the "\r\n". That adds a new line within the sprintf format. This just makes the email easier to read. Run some tests and see what works best for your content.

$old_message = $wp_new_user_notification_email['message'];
$wp_new_user_notification_email['message'] = sprintf("Message Addition\r\n");
$wp_new_user_notification_email['message'] .= $old_message;

By doing that, you pass the original message to a variable, start the email body fresh with your message, then add the original message back in.

You could add a further part of the message (like a custom sign-off) at the end using the code we originally used.

return $wp_new_user_notification_email;

This is very important. It tells the filter to go and do the changes you made. If you don't return this, none of the rest matters. You don't need to return the other arguments that you passed to this function.

What Else Can You Change In The New Email?

Logging the output of $wp_new_user_notification_email you'll find it has 4 elements:

• [to] - the address of the new user
• [subject] - default is "[%s] Your username and password info"
• [message] - contains the username and a link to reset their password
• [headers] - default is blank. You could use this to set, say a HTML email

You don't want to touch the [to] and you really should mess with [headers] unless you know what you're doing and test extensively. The only element other than [message] left is the [subject].

The way you change the subject on WordPress's default new user email is with this code:

$wp_new_user_notification_email['subject'] = sprintf("New Subject");

You may have noticed in the default that is uses "[%s]". That will add the website name to the subject line. For example, such an email from this site would be "[Intelliwolf]".

If you wanted to use your site name in that same way, the code you'd use might look like:

$wp_new_user_notification_email['subject'] = sprintf("Your Login at %s", $blogname);

This will put $blogname wherever you have put %s.

You could use this same technique in the message body.

How to send the wp_mail() as HTML

I don't recommend sending the welcome email with HTML formatting because you don't want to do anything to impact deliverability for a password reset email.

If you really did want to send the email formatted as HTML, rather than plaintext, you would add the following line above the return:

$wp_new_user_notification_email['headers'] = array('Content-Type: text/html; charset=UTF-8');

Then you would add your HTML formatted message to the ['message'] section.

Further Personalise the Email Message

If you really want to personalise the email message, remember that you have access to $user, which is the WP_User object.

Some of the key fields you might be interested in for personalising these emails are:

• $user->data->user_email - their email address
• $user->data->user_registered - the date & time of registration
• $user->data->user_login - the Username they entered
• $user->ID - their WordPress user ID

If you found this guide helpful, we'd love to hear from you in the comments section below.