Steve Taylor photo

Customizing the new user email with a pluggable function

A client of mine loves the new “Send password” checkbox on the Add New User page in WordPress. Before 2.8, users registering through the registration form got the email with their account details; but if an admin added them through Add New User, they didn’t. Now admins can choose whether or not to trigger the email.

But the default copy is pretty sparse. The ability to customize the copy in it is a good candidate for inclusion in the WP core, but it’s relatively easy to hack it for now—thanks to pluggable functions.

I’ve just properly learned about pluggable functions. A few hazy pieces I’ve been kind of aware of have fallen into place. Basically, in /wp-includes/pluggable.php are a load of functions that you can override. For every function in this file, WP checks if someone’s already defined it elsewhere (i.e. in the plugin code that’s been loaded for the request), and only defines the default function if it doesn’t already exist.

The function to override for customizing new user emails is wp_new_user_notification(), but the process for overriding any of these pluggable functions is roughly the same:

  1. Copy the whole function from pluggable.php. Include the function_exists() check it’s wrapped in. If you include this, your function will still get priority over the WP core; it’ll just prevent fatal errors if you activate a plugin that happens to have overridden the same function.
  2. Paste the function code into your plugin.
  3. Customize!

NOTE! Regular readers will know I’m partial to including persistent customizations into my custom theme’s functions.php. However, this technique does not work in theme code. It seems that plugins are loaded first, then pluggable.php, then the theme. So if your function override is in your theme, you’ll clash with the default function. You need to create a plugin, however basic. Here’s one to save you a bit of time if you’re new to writing plugins:

<?php
/*
Plugin Name: Custom New User Email
Description: Changes the copy in the email sent out to new users
*/

// Redefine user notification function
if ( !function_exists('wp_new_user_notification') ) {
	function wp_new_user_notification( $user_id, $plaintext_pass = '' ) {
		$user = new WP_User($user_id);

		$user_login = stripslashes($user->user_login);
		$user_email = stripslashes($user->user_email);

		$message  = sprintf(__('New user registration on your blog %s:'), get_option('blogname')) . "rnrn";
		$message .= sprintf(__('Username: %s'), $user_login) . "rnrn";
		$message .= sprintf(__('E-mail: %s'), $user_email) . "rn";

		@wp_mail(get_option('admin_email'), sprintf(__('[%s] New User Registration'), get_option('blogname')), $message);

		if ( empty($plaintext_pass) )
			return;

		$message  = __('Hi there,') . "rnrn";
		$message .= sprintf(__("Welcome to %s! Here's how to log in:"), get_option('blogname')) . "rnrn";
		$message .= wp_login_url() . "rn";
		$message .= sprintf(__('Username: %s'), $user_login) . "rn";
		$message .= sprintf(__('Password: %s'), $plaintext_pass) . "rnrn";
		$message .= sprintf(__('If you have any problems, please contact me at %s.'), get_option('admin_email')) . "rnrn";
		$message .= __('Adios!');

		wp_mail($user_email, sprintf(__('[%s] Your username and password'), get_option('blogname')), $message);

	}
}

?>

Copy the code, paste it into a text file, and save it as something like custom_new_user_email.php. Lines 10-23 are as you’ll find them in pluggable.php. You’ll want to customize the message that’s built up in the subsequent lines. Once you’re done, upload it to /wp-content/plugins/ and activate it.

UPDATE: Anyone interested in this kind of thing might find this WP Engineer post useful, too.

12 comments

  1. Joseph avatar Joseph

    Nice plugin!

    Please, allow a couple of questions;

    1 How do I change

    @wp_mail(get_option('admin_email')

    for a custom “noreply” email address? Instead of sending the email from admin@mydomain.com I’d like to send it from a non-existent noreply@whatever.com

    2 In the new user email you add a custom subject field but how can I set a custom “from” field?

    Thanks

  2. Steve Taylor avatar Steve Taylor

    Hi Joseph… Good question! For changing the the “From” address, it looks like wp_mail takes extra parameters, including an optional string or array of headers. I think you can specify the “From” address in here. I’ve not done this, but just follow the code trail. Check out the wp_mail function in /wp-includes/pluggable.php (notice that as it’s in here you can override the whole function if you want to – overkill though, I think!). I imagine it’s all a big wrapper for PHP’s mail function… Hope that puts you in the right direction.

  3. So let’s say we redeclare a pluggable function in our plugin and it works fine. Now another plugin too redeclares the same function. Won’t these two clash? Is there a way for two plugins to use pluggable functions and still respect the sanctity?

  4. Steve Taylor avatar Steve Taylor

    If two plugins redeclare the same pluggable function, naturally they’ll clash. Thinking about a situation where you’d enable two plugins to perform different operations on the same functionality—well, that’s getting into hooks territory. Not sure why WP has the new user email managed via a pluggable function rather than a filter or action, but there it is.

  5. Mike avatar Mike

    This works great! Thank you! Is there a way to customize the subject line of the email? Currently the plugin uses the site name of the site as the subject line. It would be great if there was a way to customize this.

  6. Dave avatar Dave

    Nice one, Bro! I am working on it. I am a neophyte on customizing functions and I need all the help that I can get. I am now on getting current user and validating authentic cookie. Do you have a tutorial for that? Thanks.

  7. juries avatar juries

    Steve can you make a tutorial on helping out with current user and validating authentic cookie? I’m sure this will help may users.

  8. There’s a lot of tutorials I could and would love to do. At the moment, though, what I have to do is move house and finish client projects that are running over! Sorry, you’ll have to try Google ;-)

  9. Unfortunately it took me a while to find this article. Glad I did though, it’s got everything I needed to know on how to “plug” this function and why it works the way it does. Thanks very much Steve.

Leave a comment

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>