View source
<h2 id="html-mail"><a href="http://drupal.org/project/htmlmail">HTML Mail</a></h2>
<p>Lets you theme your messages the same way you theme the rest of your website.</p>
<h3 id="requirements"><a href="http://www.dict.org/bin/Dict?Form=Dict2&Database=*&Query=requirement">Requirements</a></h3>
<ul>
<li>
<p><a href="http://drupal.org/node/1135590">Autoload 6.x-2.1</a> <em>(New for 6.x-2.28)</em></p>
</li>
<li>
<p><a href="http://drupal.org/project/mailsystem">Mail System 6.x-2.x</a></p>
</li>
</ul>
<h3 id="installation"><a href="http://drupal.org/documentation/install/modules-themes/modules-5-6">Installation</a></h3>
<p>The following additional modules, while not required, are highly recommended:</p>
<ul>
<li>
<dl>
<dt><a href="http://drupal.org/project/echo">Echo</a></dt>
<dd>Wraps your messages in a drupal theme. Now you can "brand" your messages with the same logo, header, fonts, and styles as your website.</dd>
</dl>
</li>
<li>
<dl>
<dt><a href="http://drupal.org/project/emogrifier">Emogrifier</a></dt>
<dd>Converts stylesheets to inline style rules, for consistent display on mobile devices and webmail.</dd>
</dl>
</li>
<li>
<dl>
<dt><a href="http://drupal.org/project/mailmime">Mail MIME</a></dt>
<dd>Provides a text/plain alternative to text/html emails, and automatically converts image references to inline image attachments.</dd>
</dl>
</li>
<li>
<dl>
<dt><a href="http://drupal.org/project/pathologic">Pathologic</a></dt>
<dd>Converts urls from relative to absolute, so clickable links in your email messages work as intended.</dd>
</dl>
</li>
<li>
<dl>
<dt><a href="http://drupal.org/project/filter_transliteration">Transliteration</a></dt>
<dd>
<p>Converts non-ASCII characters to their US-ASCII equivalents, such as from Microsoft "smart-quotes" to regular quotes.</p>
</dd>
<dd>
<p><em>Also available as a <a href="http://drupal.org/node/1095278#comment-4219530">patch</a>.</em></p>
</dd>
</dl>
</li>
</ul>
<h3 id="updating-from-previous-versions"><a href="http://drupal.org/node/250790">Updating from previous versions</a></h3>
<p>The <a href="http://drupal.org/node/1119548">6.x-2.x</a> branch shares 94% of its code with the <a href="http://drupal.org/node/1106064">7.x-2.x</a> branch, but only 8% of its code with the <a href="http://drupal.org/node/329828">6.x-1.x</a> branch.</p>
<p>Let your compatibility expectations be adjusted accordingly.</p>
<ul>
<li>
<p>Check the module dependencies, as they have changed. The latest version of <a href="http://drupal.org/project/htmlmail">HTML Mail</a> depends on:</p>
<ul>
<li><a href="http://drupal.org/project/autoload">Autoload</a></li>
<li><a href="http://drupal.org/project/mailsystem">Mail System</a> (6.x-2.2 or later)</li>
</ul>
</li>
<li>
<p>Run <code>update.php</code> <em>immediately</em> after uploading new code.</p>
</li>
<li>
<p>The user-interface for adding email header and footer text has been removed. Headers and footers may be added by template files and/or by enabling the <a href="http://drupal.org/project/echo">Echo</a> module.</p>
</li>
<li>
<p>Any customized filters should be carefully tested, as some of the template variables have changed. Full documentation is provided both on the module configuration page (Click on the <u>Instructions</u> link) and as comments within the <code>htmlmail.tpl.php</code> file itself.</p>
</li>
<li>
<p>The following options have been removed from the module settings page. In their place, any combination of <a href="http://drupal.org/project/modules/?filters=type%3Aproject_project%20tid%3A63%20hash%3A1hbejm%20-bs_project_sandbox%3A1%20bs_project_has_releases%3A1">over 200 filter modules</a> may be used to create an email-specific <a href="http://drupal.org/node/779050">text format</a> for post-template filtering.</p>
<ul>
<li><a href="http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_autop/6">Line break converter</a></li>
<li><a href="http://api.drupal.org/api/drupal/modules--filter--filter.module/function/_filter_url/6">URL Filter</a></li>
<li><a href="http://drupal.org/project/rel_to_abs">Relative Path to Absolute URLs</a></li>
<li><a href="http://www.pelagodesign.com/sidecar/emogrifier/">Emogrifier</a></li>
<li><a href="http://drupal.org/project/token">Token support</a></li>
</ul>
</li>
<li>
<p>Full MIME handling, including automatic generation of a plaintext alternative part and conversion of image references to inline image attachments, is available simply by enabling the <a href="http://drupal.org/project/mailmime">Mail MIME</a> module.</p>
</li>
</ul>
<h3 id="configuration"><a href="http://drupal.org/files/images/htmlmail_settings_2.thumbnail.png">Configuration</a></h3>
<p>Visit the <a href="http://drupal.org/project/mailsystem">Mail System</a> settings page at <u>admin/settings/mailsystem</u> to select which parts of Drupal will use <a href="http://drupal.org/project/htmlmail">HTML Mail</a> instead of the <a href="http://api.drupal.org/api/drupal/modules--system--system.mail.inc/class/DefaultMailSystem/7">default</a> <a href="http://api.drupal.org/api/drupal/includes--mail.inc/function/drupal_mail_system/7">mail system</a>.</p>
<p>Visit the <a href="http://drupal.org/project/htmlmail">HTML Mail</a> settings page at <u>admin/settings/htmlmail</u> to select a theme and post-filter for your messages.</p>
<h3 id="theming"><a href="http://drupal.org/documentation/theme">Theming</a></h3>
<p>The email message text goes through three transformations before sending:</p>
<ol style="list-style-type: decimal">
<li>
<h3>Template File</h3>
<p>A template file is applied to your message header, subject, and body text. The default template is the included <code>htmlmail.tpl.php</code> file. You may copy this file to your <cite>email theme</cite> directory (selected below), and use it to customize the contents and formatting of your messages. The comments within that file contain complete documentation on its usage.</p>
</li>
<li>
<h3>Theming</h3>
<p>You may choose a theme that will hold your templates from Step 1 above. If the <a href="http://drupal.org/project/echo">Echo</a> module is installed, this theme will also be used to wrap your templated text in a webpage. You use any one of <a href="http://drupal.org/project/themes">over 800</a> themes to style your messages, or <a href="http://drupal.org/documentation/theme">create your own</a> for even more power and flexibility.</p>
</li>
<li>
<h3>Post-filtering</h3>
<p>You may choose a <a href="http://drupal.org/node/779050">text format</a> to be used for filtering email messages <em>after</em> theming. This allows you to use any combination of <a href="http://drupal.org/project/modules/?filters=type%3Aproject_project%20tid%3A63%20hash%3A1hbejm%20-bs_project_sandbox%3A1%20bs_project_has_releases%3A1">over 200 filter modules</a> to make final changes to your message before sending.</p>
<p>Here is a recommended configuration:</p>
<ul>
<li>
<p><a href="http://drupal.org/project/emogrifier">Emogrifier</a> Converts stylesheets to inline style rules for consistent display on mobile devices and webmail.</p>
</li>
<li>
<p><a href="http://drupal.org/project/filter_transliteration">Transliteration</a> Converts non-ASCII text to US-ASCII equivalents. This helps prevent Microsoft "smart-quotes" from appearing as question-marks in Mozilla Thunderbird.</p>
</li>
<li>
<p><a href="http://drupal.org/project/pathologic">Pathologic</a> Converts relative URLS to absolute URLS so that clickable links in your message will work as intended.</p>
</li>
</ul>
</li>
</ol>
<h3 id="troubleshooting">Troubleshooting</h3>
<ul>
<li>
<p>Check the <a href="http://drupal.org/node/1124376">online documentation</a>, especially the <a href="http://drupal.org/node/1124934">screenshots</a>.</p>
</li>
<li>
<p>There is a special documentation page for <a href="http://drupal.org/node/1200142">Using HTML Mail together with SMTP Authentication Support</a>.</p>
</li>
<li>
<p><a href="http://drupal.org/project/simplenews">Simplenews</a> users attempting advanced theming should read <a href="http://drupal.org/node/1260178">this page</a>.</p>
</li>
<li>
<p>Double-check the <a href="http://drupal.org/project/mailsystem">Mail System</a> module settings and and make sure you selected <u><code>HTMLMailSystem</code></u> for your <u>Site-wide default mail system</u>.</p>
</li>
<li>
<p>Try selecting the <u><code>[ ]</code> <em>(Optional)</em> Debug</u> checkbox at the <a href="http://drupal.org/project/htmlmail">HTML Mail</a> module settings page and re-sending your message.</p>
</li>
<li>
<p>Clear your cache after changing any <u><code>.tpl.php</code></u> files.</p>
</li>
<li>
<p>If you use a post-filter, make sure your filter settings page looks like <a href="http://drupal.org/node/1130960">this</a>.</p>
</li>
<li>
<p>Visit the <a href="http://drupal.org/project/issues/htmlmail">issue queue</a> for support and feature requests.</p>
</li>
</ul>
<h3 id="related-modules">Related Modules</h3>
<dl>
<dt><strong>Echo</strong></dt>
<dd>
<p>http://drupal.org/project/echo</p>
</dd>
<dt><strong>Emogrifier</strong></dt>
<dd>
<p>http://drupal.org/project/emogrifier</p>
</dd>
<dt><strong>HTML Purifier</strong></dt>
<dd>
<p>http://drupal.org/project/htmlpurifier</p>
</dd>
<dt><strong>htmLawed</strong></dt>
<dd>
<p>http://drupal.org/project/htmlawed</p>
</dd>
<dt><strong>Mail MIME</strong></dt>
<dd>
<p>http://drupal.org/project/mailmime</p>
</dd>
<dt><strong>Mail System</strong></dt>
<dd>
<p>http://drupal.org/project/mailsystem</p>
</dd>
<dt><strong>Pathologic</strong></dt>
<dd>
<p>http://drupal.org/project/pathologic</p>
</dd>
<dt><strong>Transliteration</strong></dt>
<dd>
<p>http://drupal.org/project/transliteration</p>
</dd>
</dl>
<h3 id="documentation"><a href="http://drupal.org/project/documentation">Documentation</a></h3>
<p>**<a href="http://drupal.org/node/1124376">HTML Mail</a></p>
<dl>
<dt><strong><a href="http://api.drupal.org/api/drupal/modules--filter--filter.module/6">filter.module</a></strong></dt>
<dd>
<p><a href="http://api.drupal.org/api/drupal/modules--filter--filter.module/6">api.drupal.org/api/drupal/modules--filter--filter.module</a></p>
</dd>
<dt><strong><a href="http://drupal.org/documentation/install/modules-themes/modules-5-6">Installing contributed modules</a></strong></dt>
<dd>
<p><a href="http://drupal.org/documentation/install/modules-themes/modules-5-6">drupal.org/documentation/install/modules-themes/modules-5-6</a></p>
</dd>
<dt><strong><a href="http://drupal.org/documentation/theme">Theming guide</a></strong></dt>
<dd>
<p><a href="http://drupal.org/documentation/theme">drupal.org/documentation/theme</a></p>
</dd>
</dl>
<h3 id="original-author">Original Author</h3>
<ul>
<li><a href="http://drupal.org/user/1171">Chris Herberte</a></li>
</ul>
<h3 id="current-maintainer">Current Maintainer</h3>
<ul>
<li><a href="http://drupal.org/user/36148">Bob Vincent</a></li>
</ul>
