8.5.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.3.x core.api.php hook_mail_alter(&$message)
8.4.x core.api.php hook_mail_alter(&$message)
8.6.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

mattc321’s picture

If you send an email from Drupal 7 to a recipient that uses Microsoft Outlook (MS Outlook), any special characters in the email will be messed up. Characters such as quotes, single quotes, apostrophe, ampersand, hyphens, etc. they are broken and converted into ASCII strings such as &#039; &quot;

Even if the email is truly just text, and you are not using any HTML formatting, Outlook will still do this to any emails that are sent with default headers from drupal_mail.

You can use hook_mail and hook_mail_alter in Drupal to fix messed up Outlook messages by simply changing the headers to text/html. Doing this will force Outlook to stop converting characters into ASCII strings.

 * hook_mail_alter()
function hook_mail_alter(&$message) {
//figure out the message id or the key of your email
	if ($message['key'] == 'notify_ec_user') {
		$message['headers']['Content-Type'] = 'text/html; charset=UTF-8; format=flowed';