1 system.api.php hook_mail($key, &$message, $params)

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

Note that hook_mail(), unlike hook_mail_alter(), is only called on the $module argument to backdrop_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 backdrop_mail() for possible id values.
  • to: The address or addresses the message will be sent to. The formatting of this string must comply with RFC 2822.
  • subject: Subject of the email to be sent. This must not contain any newline characters, or the mail may not be sent properly. backdrop_mail() sets this to an empty string when the hook is invoked.
  • body: An array of lines containing the message to be sent. Backdrop will format the correct line endings for you. backdrop_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 backdrop_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. backdrop_mail() pre-fills several headers in this array.

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

Related topics


core/modules/system/system.api.php, line 1897
Hooks provided by Backdrop core and the System module.


function hook_mail($key, &$message, $params) {
  $account = $params['account'];
  $context = $params['context'];
  $variables = array(
    '%site_name' => config_get('system.core', 'site_name'),
    '%username' => user_format_name($account),
  if ($context['hook'] == 'taxonomy') {
    $entity = $params['entity'];
    $vocabulary = taxonomy_vocabulary_load($entity->vocabulary);
    $variables += array(
      '%term_name' => $entity->name,
      '%term_description' => $entity->description,
      '%term_id' => $entity->tid,
      '%vocabulary_name' => $vocabulary->name,
      '%vocabulary_description' => $vocabulary->description,
      '%vocabulary_machine_name' => $vocabulary->machine_name,

  // 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("\r", "\n"), '', $subject);
  $message['body'][] = backdrop_html_to_text($body);