| 6 core.php | hook_mail($key, &$message, $params) |
| 7 system.api.php | hook_mail($key, &$message, $params) |
| 8 system.api.php | hook_mail($key, &$message, $params) |
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.
Parameters
$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 must comply with RFC 2822.
- 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()
File
- modules/
system/ system.api.php, line 2451 - Hooks provided by Drupal core and the System module.
Code
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("\r", "\n"), '', $subject);
$message['body'][] = drupal_html_to_text($body);
}
Comments
A simple example with subject, body sent in from drupal_mail()
If you are confused and trying to figure out how to just simply send a mail using drupal_mail(), with a given $body and $subject, this implementation may help:
<?php
/**
* Implementation of hook_mail().
*
* A very simple hook_mail() implementation, for module "mymodule".
* This implementation expects to receive a $body, $subject, and $headers
* inside the $params sent from drupal_mail(), rather than construct
* those here in the hook.
* @see drupal_mail()
*/
function mymodule_mail($key, &$message, $params) {
if (isset($params['subject'])) {
$message['subject'] = $params['subject'];
}
if (isset($params['body'])) {
$message['body'][] = $params['body'];
}
if (isset($params['headers']) && is_array($params['headers'])) {
$message['headers'] += $params['headers'];
}
// You should really have hook_mail() doing most of the formatting,
// rather than pass in a complete $body or a $subject from drupal_mail().
// To accomplish that, you'd branch this formatting based on the value of
// $key sent with drupal_mail(), and using code like this:
// switch ($key) {
// case 'key1':
// // do something specific for mails of type key1
// break;
// case 'key2':
// // do something specific for mails of type key2
// break;
// }
// That's it - You don't do anything in your hook_mail() to actually
// send the mail, that is taken care of by the mail system automatically.
}
?>
To use this:
- Change the "mymodule" in the function name above to match your module, and place it in your module file. If you don't have a custom module, you will need to figure out how to make one, then place this hook inside it.
- Call the function like so from elsewhere in your code, replacing 'mymodule' with your custom module's actual name.
<?php
global $user; // place at the top of the function you are calling from
// ... other function code would be here
// Send email with $body and $subject constructed here:
$body = 'This is the email body text.';
$to = 'to_address@example.com';
$from = 'no-reply@example.com';
// If you are using suhosin (the hardened PHP extension) and want to use
// Cc or Bcc, then make sure that suhosin.mail.protect is not set to 2,
// or the mail will be rejected as an attack.
$header_bcc = 'bcc_address@example.com';
$header_cc = 'cc_address@example.com';
$subject = 'Subject of the email';
// you can set 'message_key' to any key you want, and process
// that in the hook_mail as shown in the commented out code.
// Or, just set it to some string and ignore it as we are here.
// You can add extra headers into the headers array here. If you
// are trying to send an HTML formatted email, please use either
// the MIME Mail or HTMLMail modules, rather than doing it
// by just setting the Content-Type.
$message = drupal_mail('mymodule', 'message_key', $to, user_preferred_language($user), array('body' => $body, 'subject' => $subject, 'headers' => array('Cc' => $header_cc, 'Bcc' => $header_bcc), $from, TRUE);
// You can check $message['result'] to see if the message sent successfully.
?>
bracket is missing
I am not sure this is the right place to inform but please add one more closing round bracket ')' after $header_bcc in drupal_mail arguments