Beyond Spots & Dots | Digital

How to use Drupal's Mail System module (D7, 2.x)

For much of my early use of Drupal, I was baffled by its mail system, by which I mean the system by which Drupal sends email (e.g. for notifications, e-Commerce receipts, etc.) Sometime after I got into Drupal 7 in late 2010, though, I started using the Mailsystem module, which helped me begin to make sense of things. This post discusses its use.

First, download and install the Mailsystem module. Once you have it installed, go to Admin » Configuration » System » Mailsystem, which is its main configuration page.

On this configuration page, there is very little so far: mostly just a field titled Site-wide default MailSystemInterface class, which contains options for changing default sending methods. If you have no additional formatting or sending modules, this page does not do much.

Formatting Your Emails

I use the HTMLMail module for formatting emails in HTML if they need to be. HTMLMail contains template files which can be moved into your default theme, thus overriding the templates contained in the module itself. One of the main reasons I like HTMLMail is because of its built-in templating hint system, which works like this:

  • htmlmail.tpl.php is the default HTMLMail template
  • htmlmail--module_name--key.tpl.php overrides the default template for specific emails. For example, a Webform submission notification email has the module name "webform" and a mail key of "submission", which means if you want to have a unique look-and-feel for a Webform submisison email, your template will look like this: htmlmail--webform--submission.tpl.php.

You can create a custom module—let's say it's called example.module—that sends a special type of notification. If we want it to look different from other emails, we can create a template called htmlmail--example.tpl.php, which will theme all emails sent by this module, or, for example, htmlmail--example--special_notification.tpl.php for any email with the mail key "special_notification".

Installing HTMLMail module gives you a new option in the Mail System configuration page: "HTMLMailSystem" as the default sender. This will wrap all site-wide emails in HTML templates before delivery.

Sending Via External APIs

But what if you want to use more than one module—for instance, if you wanted to use SMTP or a third-party service like Mandrill or Postmark to send your emails? If you're not familiar, Mandrill and Postmark are examples of paid services that deliver any website's emails and provide analytics such as opens, clicks, and bounces. They are great for debugging as well as generally keeping track of your site's transactional emails. They also help reduce the chance that your email will end up in spam filters.

Adding Mandrill or Postmark is not difficult. Add and install the module as usual, and then enter the API keys the service gives you (assuming, of course, you have signed up for an account with them already). Then, revisit the Mail System configuration page. You'll notice that, if you are using Mandrill, you have to choose between "HTMLMailSystem" and "MandrillMailSystem" as the delivery mechanisms for your site. However, what if you want to use both—i.e. HTMLMail for formatting and then Mandrill for the actual delivery? Not to worry! Click the "New Class" fieldset at the bottom and select "HTMLMailSystem in the "format()" field, and "MandrillMailSystem" in the "mail()" field. Then click "Save Settings". (This may cause you problems. If so, click here for the fix.) You will now notice a new option in the "Site-wide default MailSystemInterface class" field at the top of the Mail System page, called "HTMLMailSystem__MandrillMailSystem". This setting will use both modules to deliver emails, first wrapping them in HTML and then using Mandrill for the delivery process.

Special Settings for Certain Email Types

Now, what if you want one type of email—say, the New User Welcome email—to be HTML, while the Webform Submission emails should be plain text? Ah, this is where the "New Setting" fieldset becomes handy. Open this fieldset and select the module you want (in this case "Webform"), and then type in the Key (in this case, "submission". Click "Save Settings". You will now notice a brand new <select> menu on the page, titled something like "Webform module (submission key) class", which enables you to set, say, just Mandrill (or maybe "DefaultMailSystem__MandrillMailSystem") as the class for sending Webform submissions only.

I know this sounds complex, but in plain English what this means is that by default, Drupal will use HTMLMail and Mandrill for sending emails, but in the case of, for example, Webform submission notifications, it will let you use some other setting. You can do this, of course, for any type of email coming from Drupal, be it a Commerce invoice, a notification upon completion of an Entityform, new user "welcome" emails, and on and on.

Beyond Spots & Dots | Drupal