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.


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.


Related Posts
  • Code
    Distributing Your Plugins in GitHub with Automatic UpdatesSensorsthumbnail
    This article will teach you that, with a little creative coding, you can host your own WordPress plugins in GitHub while still retaining the automatic update feature.Read More…
  • Code
    Creative Coding
    Using WordPress for Web Application Development: A ReviewApplication foundation 400
    Over the past few months, we've been taking a look at all of the features and aspects that make WordPress a potential foundation for application development. In fact, we've spent roughly 15 articles talking about all that WordPress offers. And though we'll be reviewing each of the points in this email, perhaps the biggest thing to take away that building web applications using WordPress is different than using many of the popular frameworks that are currently available namely because WordPress isn't a framework.Read More…
  • Code
    WordPress Initialization Hooks: Benefits and Common MistakesHooks
    In programming, initialization of data is important as it's where we setup the prerequisites for the application such as its attributes, its required files and data, its connection to the database, and so on. WordPress itself has a well-defined initialization procedure. Through the page life cycle, WordPress fires a number of actions many of which we've covered in previous articles. To that end, it provides a set of initialization hooks which are naturally used to initialize the application before executing its primary functionality. As plugin and theme developers, it's important to understand the use cases and common mistakes of these initialization hooks, in order to build quality applications. In this article, we are going to take a look at the importance of WordPress initialization hooks and how they are used in various scenarios.Read More…
  • Code
    Creative Coding
    Using WordPress for Web Application Development: Features: Saving DataApplication foundation 400
    When it comes to the web, almost any application that runs within your browser is backed by a data store of some type. Usually, these data stores are in the form of a type of database. Until recently, most applications were built on top of some type of SQL database, but with the rise of document-based databases such as CouchDB, other applications have begun to use other backends as well.Read More…
  • Code
    Creative Coding
    Using WordPress for Web Application Development: Features: EmailApplication foundation 400
    One of the major components of every web application is its ability to send email. Now this doesn't mean that each web application is its own mail client (though people do certainly create their own). Instead, I mean that applications normally send emails when a user signs up, a user modifies their password, when something in the system changes, or - more generally speaking - whenever something occurs for which the site owners want to notify the users.Read More…
  • Code
    Creative Coding
    Using WordPress for Web Application Development: Understanding Events, Actions, and FiltersApplication foundation 400
    Throughout this series, we've been taking a look at how WordPress can be used for building web applications. Up to this point, we've established that WordPress is a foundation - rather than a framework - and we've talked a bit about how we need to avoid trying to shoehorn WordPress into another type of design pattern than that of its native type.Read More…