Altering someone else's emails

Drupal is powerful not only because it allows us to add our own functionality but also because it allows us to alter the existing functionality. An important vector for doing this are the alter hooks. Remember these from Chapter 2, Creating Your Own Module? These are hooks that are used to change the value of an array or object before it is used for whatever purpose it was going to be used for. When it comes to sending mails, we have an alter hook that allows us to change things on the mail definition before it goes out--hook_mail_alter(). For our module, we don't need to implement this hook. However, for the sake of making it complete, let's take a look at how we could use this hook to, for example, change the header of an existing outgoing email:

/**
 * Implements hook_mail_alter().
 */
function hello_world_mail_alter(&$message) {
  switch ($message['key']) {
    case 'hello_world_log':
      $message['headers']['Content-Type'] = 'text/html; charset=UTF-8; format=flowed; delsp=yes';
      break;
  }
}

So, what is going on here? First of all, this hook implementation gets called in each module it is implemented in. It's not like hook_mail() in this respect, as it allows us to alter mails defined in our module and sent from other modules as well. However, in our example, we will just alter the mail we defined earlier.

The only parameter (passed by reference as it is usual with alter hooks) is the $message array, which contains all the things we built in hook_mail(), as well as the key (template) and other things added by the mail manager itself, such as the headers. So, in our example, we are setting an HTML header so that whatever is getting sent out could be rendered as an HTML. After this hook is invoked, the mail system formatter is also called, which, in the case of the PhpMail plugin, transforms all HTML tags into plain text, essentially canceling out our header. However, if we implement our own plugin, we can prevent that and successfully send out HTML emails with proper tags and everything.

So, that is basically all there is to altering existing outgoing mails. Next, we will take a look at how we can create our own mail plugin that uses a custom external mail system. We won't go into details here, but we will prepare the architecture that will allow us to bring in the API we need and use it easily.