This module allows Drupal to send beautifully styled HTML emails instead of plain text. It uses Twig templates for customization, automatically inlines CSS for consistent rendering across email clients, and provides plain-text fallbacks.
Magic HTML Mail sends Drupal email as HTML from one themeable Twig template, with a plain-text alternative. Any module's hook_mail() message gets a clean, responsive HTML version with no changes to that module.
Features
- One template for all mail:
html-mail.html.twig, rendered in a mail theme of your choice, even when mail is sent from an admin page, drush or cron. A theme can override it like any template. - Branding without code: name, logo, colors, font stack and a default footer, set on the settings page. There is also a Send test message button.
- Optional hints for sending modules: a heading, a one-time code, a button, a summary card, a notice and an unsubscribe link. A module adds them under
$message['html_mail'], and they are ignored when this module is not installed. - Plain-text alternative: the original text body is kept as the text part. Without hints, it becomes the HTML body paragraph by paragraph, with links made clickable.
- Inline styles: email clients ignore most CSS, so the template styles everything inline, and its
|mail_styleTwig filter adds inline styles to the body's plain tags. - Safe hints: HTML hints are filtered down to plain tags, and dangerous URL protocols are removed.
Transports (submodules)
- Magic HTML Mail: Symfony Mailer (
html_mail_symfony) for sites where Drupal Symfony Mailer replaces the mail manager. It replaces Symfony Mailer's wrapper for messages that carry hints, and for the modules you list (by defaultuser, core's account emails). - Magic HTML Mail: Amazon SES (
html_mail_ses) is a mail plugin for Amazon SES. It sends the HTML and text parts and passesList-Unsubscribeheaders through for one-click unsubscribe (RFC 8058).
Post-installation
composer require drupal/html_mail, then enablehtml_mailand one transport submodule.- Go to Configuration » System » Magic HTML Mail (
/admin/config/system/html-mail). You need the Administer Magic HTML Mail permission. - Set the site URL if mail is sent from cron or drush. Set the logo, colors and footer, then send a test message.
- Optional: copy
templates/html-mail.html.twiginto your theme to change the layout.
Requirements
- Drupal 10.3 or 11.
- One of the transports above: Drupal Symfony Mailer 1.5+ or Amazon SES 3.1+.
Recommended modules
- Magic Login sends passwordless sign-in links and codes. It uses Magic HTML Mail's hints for its button and code.
Similar projects
- HTML Mail (
htmlmail) themes mail per module and key through Mail System, using its own mail plugin. Magic HTML Mail uses a single template that any theme can override, adds hints for sending modules, and sends through Symfony Mailer or Amazon SES. - Mime Mail builds MIME messages with attachments and embedded images through Mail System. Magic HTML Mail does not handle attachments, and leaves MIME building to the transport.
- Drupal Symfony Mailer has its own HTML wrapper and policies. Magic HTML Mail runs on top of it and replaces that wrapper for the modules you choose.
AI disclosure
This disclosure follows Drupal's AI contribution policy. Much of this module's code, tests and documentation was written with Claude, and the commits that used it carry a Co-Authored-By trailer. I review each change, maintain the module, and take responsibility for it. The security design is described in SECURITY.md. Every push runs drupal.org's GitLab CI: PHPCS, PHPStan level 8 (Drupal 11.4), cspell, ESLint, composer validation, and unit, kernel and functional tests on Drupal 10.6 and 11.4.
Documentation
The README lists every setting, every hint, and how to theme the template.
Report bugs and ideas in the issue queue.
Ask your assistant about Magic HTML Mail
Check compatibility with your Drupal and PHP version, maintenance and security coverage, from current release data. How it works
Depends on
Dependencies of the latest stable release
No dependencies recorded for this project.
Required by
Tracked projects that depend on this one
No tracked projects depend on this one yet.