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 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 for the email you want to send. It's referred to in code as the key or message ID, but I believe that template is a better word to describe it. And you guessed it, it works by implementing a hook.

The second thing that we will need to do is use the Drupal mail manager to send the 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.

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 emails. If we create our own mail system, that will mean creating a new plugin. Also, the plugin itself is the one actually delivering the emails, the manager simply deferring 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 a few bits of theory, 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 is an error.