Skip to main content
drupalreleases

Use direct release data with your AI assistant.

Learn more

Magic HTML Mail

No security coverage Under active development 4 sites

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_style Twig 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 default user, 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 passes List-Unsubscribe headers through for one-click unsubscribe (RFC 8058).

Post-installation

  1. composer require drupal/html_mail, then enable html_mail and one transport submodule.
  2. Go to Configuration » System » Magic HTML Mail (/admin/config/system/html-mail). You need the Administer Magic HTML Mail permission.
  3. Set the site URL if mail is sent from cron or drush. Set the logo, colors and footer, then send a test message.
  4. Optional: copy templates/html-mail.html.twig into 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.

Drupal 10–11 PHP >=8.1

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.

Activity

Tracked releases
4
Tracked since
Oct 2026
Latest release
19 hours ago
Releases (12 mo)
4 ▲ from 0
Maintenance
Active

Release Timeline

Releases

Version Type Core PHP Release date
1.0.3 Stable 10–11 PHP >=8.1 Nov 21, 2026
1.0.2 Stable 10–11 PHP >=8.1 Nov 16, 2026
1.0.1 Stable 10–11 PHP >=8.1 Oct 13, 2026
1.0.0 Stable 10–11 PHP >=8.1 Oct 8, 2026