function hook_mail

Same name and namespace in other branches
  1. 9 core/core.api.php \hook_mail()
  2. 8.9.x core/core.api.php \hook_mail()
  3. 10 core/core.api.php \hook_mail()
  4. 11.x core/core.api.php \hook_mail()

Prepare a message based on parameters; called from drupal_mail().

Note that hook_mail(), unlike hook_mail_alter(), is only called on the $module argument to drupal_mail(), not all modules.


$key: An identifier of the mail.

$message: An array to be filled in. Elements in this array include:

  • id: An ID to identify the mail sent. Look at module source code or drupal_mail() for possible id values.
  • to: The address or addresses the message will be sent to. The formatting of this string will be validated with the PHP e-mail validation filter.
  • subject: Subject of the e-mail to be sent. This must not contain any newline characters, or the mail may not be sent properly. drupal_mail() sets this to an empty string when the hook is invoked.
  • body: An array of lines containing the message to be sent. Drupal will format the correct line endings for you. drupal_mail() sets this to an empty array when the hook is invoked.
  • from: The address the message will be marked as being from, which is set by drupal_mail() to either a custom address or the site-wide default email address when the hook is invoked.
  • headers: Associative array containing mail headers, such as From, Sender, MIME-Version, Content-Type, etc. drupal_mail() pre-fills several headers in this array.

$params: An array of parameters supplied by the caller of drupal_mail().

Related topics

8 functions implement hook_mail()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

contact_mail in modules/contact/contact.module
Implements hook_mail().
drupal_mail in includes/
Composes and optionally sends an e-mail message.
drupal_wrap_mail in includes/
Performs format=flowed soft wrapping for mail (RFC 3676).
system_mail in modules/system/system.module
Implements hook_mail().
update_mail in modules/update/update.module
Implements hook_mail().

... See full list


modules/system/system.api.php, line 2602


function hook_mail($key, &$message, $params) {
    $account = $params['account'];
    $context = $params['context'];
    $variables = array(
        '%site_name' => variable_get('site_name', 'Drupal'),
        '%username' => format_username($account),
    if ($context['hook'] == 'taxonomy') {
        $entity = $params['entity'];
        $vocabulary = taxonomy_vocabulary_load($entity->vid);
        $variables += array(
            '%term_name' => $entity->name,
            '%term_description' => $entity->description,
            '%term_id' => $entity->tid,
            '%vocabulary_name' => $vocabulary->name,
            '%vocabulary_description' => $vocabulary->description,
            '%vocabulary_id' => $vocabulary->vid,
    // Node-based variable translation is only available if we have a node.
    if (isset($params['node'])) {
        $node = $params['node'];
        $variables += array(
            '%uid' => $node->uid,
            '%node_url' => url('node/' . $node->nid, array(
                'absolute' => TRUE,
            '%node_type' => node_type_get_name($node),
            '%title' => $node->title,
            '%teaser' => $node->teaser,
            '%body' => $node->body,
    $subject = strtr($context['subject'], $variables);
    $body = strtr($context['message'], $variables);
    $message['subject'] .= str_replace(array(
    ), '', $subject);
    $message['body'][] = drupal_html_to_text($body);

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.