How email works in Drupal

Note that in this document we're going to put the word "template" in quotes, so that it's clear that when we use this word we're talking about a specific concept that in Drupal is used only when talking about email. In this context, "template" will NEVER mean a Twig Template (found in a .html.twig file) or a PHP Template template (found in a .tpl.php file). Although awkward to read and write, I hope using "template" in this manner will help prevent confusion about the already way-too-complicated process that Drupal uses to send email.

First, a definition of "template":

When talking about Drupal email, we use the word "template" to refer to a pre-set email. This is something like a form letter, where the subject and contents are fixed and unchanging with the exception of some placeholders that are filled in only when you're ready to send the email. Many standalone email programs (e.g. Gmail, Outlook, etc.) have this concept of a "template", but the big difference in Drupal is that ALL emails must ALWAYS be sent with a "template", while standalone email programs typically send individually-composed messages by default and only use "templates" sometimes, for group mailings or similar tasks.

There are three pieces of code involved with sending email in Drupal:

1. Sending module
   • The sending module is the module that calls MailManager::mail().
   • The sending module doesn't control the contents or subject of the email - it just specifies which "template" to use and what address to send the email to.
2. "Template" module
   • The module that provides the "template" is a module that implements hook_mail().
   • This module may provide a UI for changing the text content of this "template".
   • This module may support use of Tokens in the "template" text content.
   • This module is often the same as the Sending module described above, but this is not required.
3. Mail plugin
   • Core Drupal uses a Mail plugin first to format the completed "template" then to send the email. It is important to remember that Mail plugins have two distinct functions: "formatting" and "sending".
   • The only plugin provided by core Drupal is PhpMail. The PhpMail plugin "formats" the email by ALWAYS converting all "template" contents into plain text. The PhpMail plugin "sends" the email by using the native PHP mail() function. This requires that you have PHP set up properly to send email on your server.

Example:

The core Drupal password recovery email. This is the email that is sent when you fill out and submit the form at /user/password. In this case:

1. Sending module
   • The sending module is the core Drupal user module.
2. "Template" module
   • The "template" module is also the core Drupal user module.
   • Text contents of these "templates" may be edited at /admin/config/people/accounts
   • Tokens may be used in this text content.
3. Mail plugin
   • The Mail plugin is the core Drupal PhpMail plugin.

The sending module decides who to send the email to and which "template" to use. Then the module providing the "template" fills in the placeholders (such as the recipient, as well as any token replacements) and hands the result off to core Drupal which uses a Mail plugin to complete the task. Because the core Drupal PhpMail plugin is used, this password recovery email will always be plain text - it cannot contain HTML without the help of a contributed module like Mime Mail.