When formatting an email message with a given $module and $key, HTML Mail will use the first template file it finds from the following list:

1. htmlmail--$module--$key.tpl.php
2. htmlmail--$module.tpl.php
3. htmlmail.tpl.php

For each filename, HTML Mail looks first in the chosen Email theme directory, then in its own module directory, before proceeding to the next filename.

For example, if example_module sends mail with:

drupal_mail("example_module", "outgoing_message" ...)

the possible template file names would be:

1. htmlmail--example_module--outgoing_message.tpl.php
2. htmlmail--example_module.tpl.php
3. htmlmail.tpl.php

Template files are cached, so remember to clear the cache by visiting admin/config/development/performance after changing any .tpl.php files.

The following variables available in this template:

$body

The message body text.

$module

The first argument to drupal_mail(), which is, by convention, the machine-readable name of the sending module.

$key

The second argument to drupal_mail(), which should give some indication of why this email is being sent.

$message_id

The email message id, which should be equal to "{$module}_{$key}".

$headers

An array of email (name => value) pairs.

$from

The configured sender address.

$to

The recipient email address.

$subject

The message subject line.

$body

The formatted message body.

$language

The language object for this message.

$params

Any module-specific parameters.

$template_name

The basename of the active template.

$template_path

The relative path to the template directory.

$template_url

The absolute URL to the template directory.

$theme

The name of the Email theme used to hold template files. If the Echo module is enabled this theme will also be used to transform the message body into a fully-themed webpage.

$theme_path

The relative path to the selected Email theme directory.

$theme_url

The absolute URL to the selected Email theme directory.

$debug

TRUE to add some useful debugging info to the bottom of the message.

Other modules may also add or modify theme variables by implementing a MODULENAME_preprocess_htmlmail(&$variables) hook function.

' . t('Choose the theme that will hold your customized templates from Step 1 above.') . '

' . (module_exists('echo') ? t('The templated text will be styled by your chosen theme. This lets you use any one of over 800 themes to style your messages. Creating an email-specific sub-theme lets you use the full power of the drupal theme system to format your messages.', array( '!themes' => 'http://drupal.org/project/themes', '!theme_system' => 'http://drupal.org/documentation/theme', ) ) : t('If you install and enable the Echo module, the theme you select will also be used to style your messages as if they were pages on your website.', array( '!echo' => 'http://drupal.org/project/echo' ) ) ) . '

' . (module_exists('mailmime') ? t('Since you have the Mail MIME module installed, your images will be automatically converted to inline attachments, and a plain-text alternative will be available to recipients who prefer it.', array('!mailmime' => 'http://drupal.org/project/mailmime') ) : t('If you install the Mail MIME module, images in your emails will be automatically converted to inline attachments, and a plain-text alternative will be made available. This prevents your recipients from seeing broken image links and scary security warnings when they don\'t have the sender\'s address in their email addressbook. Mail MIME also allows HTML Mail to handle MIME-formatted messages sent by other modules such as Send by-email.', array( '!mailmime' => 'http://drupal.org/project/mailmime', '!print' => 'http://drupal.org/project/print', ) ) ) . '

' . t('You may choose a text format to be used for filtering email messages after theming. This allows you to use any combination of over 200 filter modules to make final changes to your message before sending.', array( '!formats' => url('admin/config/content/formats'), '!filters' => url('http://drupal.org/project/modules/?filters=type%3Aproject_project%20tid%3A63%20hash%3A1hbejm%20-bs_project_sandbox%3A1%20bs_project_has_releases%3A1'), ) ) . '

' . t('Here is a recommended configuration:') . '

• ' . t('Emogrifier', array('!emogrifier' => url('http://drupal.org/project/emogrifier')) ) . '

  ' . t('Converts stylesheets to inline style rules for consistent display on mobile devices and webmail.') . '

• ' . t('Transliteration', array('!transliteration' => url('http;//drupal.org/project/filter_transliteration')) ) . '

  ' . t('Converts non-ASCII text to US-ASCII equivalents. This helps prevent Microsoft smart-quotes from appearing as question-marks in Mozilla Thunderbird.' ) . '

• ' . t('Pathologic', array('!pathologic' => url('http://drupal.org/project/pathologic')) ) . '

  ' . t('Converts relative URLS to absolute URLS so that clickable links in your message will work as intended.') . '