8.3.x core.api.php hook_mail_alter(&$message)
8.0.x core.api.php hook_mail_alter(&$message)
8.1.x core.api.php hook_mail_alter(&$message)
8.2.x core.api.php hook_mail_alter(&$message)
8.4.x core.api.php hook_mail_alter(&$message)
5.x core.php hook_mail_alter(&$mailkey, &$to, &$subject, &$body, &$from, &$headers)
6.x core.php hook_mail_alter(&$message)
7.x system.api.php hook_mail_alter(&$message)

Alter an email message created with the drupal_mail() function.

hook_mail_alter() allows modification of email messages created and sent with drupal_mail(). Usage examples include adding and/or changing message text, message fields, and message headers.

Email messages sent using functions other than drupal_mail() will not invoke hook_mail_alter(). For example, a contributed module directly calling the drupal_mail_system()->mail() or PHP mail() function will not invoke this hook. All core modules use drupal_mail() for messaging, it is best practice but not mandatory in contributed modules.


$message: An array containing the message data. Keys in this array include:

  • 'id': The drupal_mail() id of the message. 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.
  • 'from': The address the message will be marked as being from, which is either a custom address or the site-wide default email address.
  • 'subject': Subject of the email to be sent. This must not contain any newline characters, or the email may not be sent properly.
  • 'body': An array of strings containing the message text. The message body is created by concatenating the individual array strings into a single text string using "\n\n" as a separator.
  • 'headers': Associative array containing mail headers, such as From, Sender, MIME-Version, Content-Type, etc.
  • 'params': An array of optional parameters supplied by the caller of drupal_mail() that is used to build the message before hook_mail_alter() is invoked.
  • 'language': The language object used to build the message before hook_mail_alter() is invoked.
  • 'send': Set to FALSE to abort sending this email message.

See also


Related topics

1 function implements hook_mail_alter()

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

simpletest_mail_alter in modules/simpletest/simpletest.module
Implements hook_mail_alter().
1 invocation of hook_mail_alter()
drupal_mail in includes/mail.inc
Composes and optionally sends an e-mail message.


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


function hook_mail_alter(&$message) {
  if ($message['id'] == 'modulename_messagekey') {
    if (!example_notifications_optin($message['to'], $message['id'])) {
      // If the recipient has opted to not receive such messages, cancel
      // sending.
      $message['send'] = FALSE;
    $message['body'][] = "--\nMail sent out from " . variable_get('site_name', t('Drupal'));


millwardesque’s picture

For versions of Drupal 7 prior to 7.12, you'll need to manually apply the patch at http://drupal.org/node/800434

From 7.12 onward, this patch was added to core.

fragtom’s picture

In my drupal 7 enviroment the message identifier is $message['key'] instead of $message['id']..

meustrus’s picture

It would appear that both 'module' and 'key' are provided in $message, and 'id' is the concatenation of 'module' . "_" . 'key'.

kalidasan’s picture



Alter/ update "From:" field

function yourmodule_mail_alter(&$message) {
  $message['from'] = $message['headers']['From'] = '"Full Name" <email@address.com>';
function mymodule_mail_alter(&$message){
  $default_from = variable_get('site_mail', ini_get('sendmail_from'));
  if($message['from'] == $default_from){
    $message['from'] = '"'. variable_get('site_name', 'Drupal') .'" <'. $default_from .'>';
    $message['headers']['From'] = $message['headers']['Sender'] = $message['headers']['Return-Path'] = $message['headers']['Errors-To'] = $message['headers']['Reply-To'] = $message['from'];
jonas139’s picture

Thanks kalidasan, it saved me a lot of time!

Qandeel’s picture

Above in the list $message['key'] is missing, the owner of this page needs to add this missing piece in to api documentation for hook_mail_alter