Creating Customized Comment Emails: Understanding the API

When it comes to working with emails in WordPress, most users are familiar with the basic features and/or notifications.

Specifically, we're used to seeing emails for:

User registrations
Password reminders
Comment notifications
...and so on.

When it comes to building more advanced themes - or even applications - it's not uncommon to outsource email functionality in order to provide a better experience for our users.

That is to say that if we're going to be emailing them, then we'd like to make the email as good looking as possible. This usually requires that we include consistent branding, a more flexible layout, and a greater number of styled elements.

For certain emails, this makes total sense especially when it comes to welcome messages, newsletters, and things of the like.

But if you're wanting to provide a consistent experience across your site from the way it looks to, say, how comment notifications emails appear, then you can do that with the native WordPress API.

So in this two-part series, we're going to take a look at the API for customizing our comment moderation and comment notification emails.

In the first part of the series, we're going to review the function responsible for sending the email and the hooks it provides. We're going to review the capabilities of the hook, and then we're going to survey how the entire process works.

After that, we'll end the series by taking a look at a practical example of how we can completely customize the comment notification email to suit our needs.

The Function and The Hooks

The function that's responsible for sending comment notification emails is the wp_notify_postauthor function.

At the time of writing this article, the documentation for this function is a little weak. Although it properly describes what the function accepts and what it returns, its description is a bit unclear.

It reads:

This function can be replaced via plugins. If plugins do not redefine these functions, then this will be used instead.

Sanitizes a URL for use in a redirect.

Now, the two most important takeaways from this part of the documentation are as follows:

"The function can be replaced via plugins."
"Sanitizes a URL for use in a redirect."

Perhaps the most cryptic part of the documentation is that the function can be replaced wholesale via plugins; however, the function also offers several filters that we can hook into in order to manipulate the data.

In fact, this brings up an important strategy when it comes to developing open source projects.

A Strategy For Open Source Development

One of the most powerful aspects of open source development is its very nature: that it's open source.

Case in point: when documentation leaves you with something to be desired, then the next best thing is to open the source code and review exactly what's happening.

To do this, it's a simple matter of locating the function in the core application. You can do this by your IDE or by browsing the WordPress Trac.

Regardless, for the purposes of this post, the function in question is located in wp-includes/pluggable.php.

Once we've located it, we can then begin locating which aspects of the plugin are overridable by plugins.

Its Capabilities

Note that part of what makes WordPress so powerful is its hook system. Recall from an earlier post that there are two types of hooks: Actions and Filters.

Actions are events that fire in the WordPress page life cycle when certain things have occurred.
Filters are functions that are primarily responsible for intercepting, managing, and returning data before rendering it to the browser.

Because we want to alter the content and/or styling of an email, then we're looking for functionality specifically for rendering content of an email. Therefore, we must be looking for a filter.

And since we're looking for functionality specifically for rendering content for an email, then we must be looking for a filter.

So, with all of that said, we're looking for a call (or calls) to apply_filters and this function provides three:

$notify_message = apply_filters('comment_notification_text', $notify_message, $comment_id);
$subject = apply_filters('comment_notification_subject', $subject, $comment_id);
$message_headers = apply_filters('comment_notification_headers', $message_headers, $comment_id);

But what good is locating the filters if we don't actually know how to use them?

How It Works

In reviewing the code above, you'll see that WordPress is filtering the data through three specific functions each of which seem relatively cleer, right?

comment_notification_text is responsible for managing the actual content of the email
comment_notification_subject manges the subject line of the email
comment_notification_headers deal with how the email is rendered (typically this is where we set plain text versus, say, HTML).

Easy enough, right? Of course, this is really only half of it.

In addition to understanding what each function does, it isn't worth much until we know how to actually use the filters.

Conclusion

In the next article, we're going to build our own plugin that provides customized comment notification emails.

Specifically, we'll aim to provide a more consistent experience with the rest of the site, we'll customize the content of the email, and we'll review how and why we should be managing the headers that are sent with each email.

We'll also be using the latest theme - Twentytwelve - that ships with WordPress 3.5. So, in the meantime, go ahead and get your development environment setup so you'll be ready to go with the next article.

A Note About Documentation

One of the nicest things about open source development is the ability for anyone to contribute to the project. When we, as developers, think of contributing to a project, we often think of contributing to its codebase.

But an open source project is so much more: it includes documentation, image assets, various dependencies, and so on.

At the time of originally writing this post, the documentation for wp_notify_postauthor needed some improvement. As such, I've contributed an update to the Codex while writing this post.

A Call To Action

If you're involved in the WordPress Community in any capacity and are capable of contributing in someway - even if it's updating the documentation - then I highly urge you to do so as it helps the many thousands of people all over the globe who use WordPress.

HIGHLIGHTS OF THE DAY