The theory of the Mail API

Like before, let's first cover this API from a theoretical point of view. It's important to understand the architecture before diving into examples.

Sending emails programmatically in Drupal is a two-part job. The first thing we will need to do is define something of a template for the email in our module. This is not a template in the traditional sense, but rather a procedural data wrapper to the email you want to send. It's referred to in our code as the key or message ID, but I believe that template is a better word to describe it, and it works by--you guessed it--implementing a hook.

The second thing that we will need to do is use the Drupal mail manager to send an email using one of the defined templates and specifying the module that defines it. If this sounds confusing, don't worry, it will become clear with the example that follows its explanation later on.

The template is created by implementing hook_mail(). This hook is a special one, as it does not work like most others. It gets called by the mail manager when a client (some code) is trying to send an email for the module that implements it and with a certain template ID it defines.

The MailManager is actually a plugin manager that is also responsible for sending the emails using a mail system (plugin). The default mail system is PhpMail, which uses PHP's native mail() function to send out email. If we create our own mail system, that will mean creating a new plugin. Also, the plugin itself is the one delivering the mails as the manager defers to it. As you can see, we can't go even a chapter ahead without creating plugins.

Each mail plugin needs to implement MailInterface, which exposes two methods--format() and mail(). The first one does the initial preparation of the mail content (message concatenation, and so on), whereas the latter finalizes and does the sending.

However, how does the mail manager know which plugin to use? It checks a configuration object called system.mail, which stores the default plugin (PhpMail) and can also store overrides for each individual module and any module and template ID combination. So, we can have multiple mail plugins each used for different things. A quirky thing about this configuration object is that there is no admin form where you can specify which plugin does what. You have to adjust this configuration object programmatically as needed. One way you can manipulate this is via hook_install() and hook_uninstall() hooks. These hooks are used to perform some tasks whenever a module is installed/uninstalled. So, this is where we will change the configuration object to add our own mail plugin a bit later.

However, now that we have looked at few theories, let's take a look at how we can use the default mail system to send out an email programmatically. You remember our unfinished logger from the preceding section? That is where we will send our email whenever the logged message gets an error.