What's the point to have hook_mail_alter if I already have hook_mail?

Question

What's the point to have hook_mail_alter if I already have hook_mail?

For example, I saw that hook_mail_alter is used to add a footer to my mail message. But I could use hook_mail() to add it, instead of using 2 functions… What am I missing?

Maybe it is done to add the footer after some other function is invoked?

Answer 1

hook_mail() should be used from a module to alter its own mail message, while hook_mail_alter() should be used from a module to alter the message sent by other modules.

This is clear from the following code taken from drupal_mail():

// Build the e-mail (get subject and body, allow additional headers) by
// invoking hook_mail() on this module. We cannot use module_invoke() as
// we need to have $message by reference in hook_mail().
if (function_exists($function = $module .'_mail')) {
  $function($key, $message, $params);
}

// Invoke hook_mail_alter() to allow all modules to alter the resulting e-mail.
drupal_alter('mail', $message);

$module is the first parameter passed to drupal_mail().
It's clear the function doesn't invoke the implementation of hook_mail() of every module implementing it, but it invokes the hook just for the module calling the function.

There are other differences, such as when the two hooks are invoked (hook_mail_alter() cannot set the language for the message, which is set before hook_mail_alter() is invoked), and the parameters they get (hook_mail($key, &$message, $params) versus hook_mail_alter(&$message)).