MJML Render Engine

A Drupal theme engine that extends Twig with MJML support for building responsive email templates. Write your email templates with full Twig capabilities — variables, includes, extends, blocks — and let MJML handle the responsive HTML output.

Requires Drupal 11.3.0 or later.

What It Does

This module registers a custom theme engine named twig_mjml that plugs into Drupal's ThemeEngineInterface. Templates use the .html.twig.mjml extension and are processed in two stages:

1. Twig compiles and renders the template — resolving all variables, {% include %}, {% extends %}, and {% block %} directives
2. MJML receives the fully resolved MJML markup and converts it into responsive, cross-client HTML email

No Node.js is required at runtime. The MJML rendering is handled by a pre-built standalone binary provided by the MJML Render Binary package.

Use Cases

Transactional Emails

Render order confirmations, password resets, account notifications, and other system emails using MJML templates with Twig variables. Combine with modules like Symfony Mailer for a complete email solution.

Email Marketing Templates

Build reusable newsletter and campaign templates that render consistently across all major email clients (Gmail, Outlook, Apple Mail, Yahoo). MJML handles the complex responsive table-based layouts automatically.

Commerce Order Emails

A Technical Deep Dive into Drupal's MJML Render Engine
by Golems GABB
Create branded, responsive emails for Drupal Commerce — order receipts, shipping notifications, abandoned cart reminders — with full access to Twig's templating power and Commerce's render arrays.

Multisite Email Branding

Set up a dedicated email theme per site in a multisite environment. Each theme uses engine: twig_mjml and can have its own set of MJML templates while sharing common Twig partials via {% include %}.

Headless / Decoupled Email Rendering

Use Drupal as a backend email renderer for decoupled architectures. The theme engine produces HTML email markup that can be consumed by any mail delivery service or API.

Installation

composer require drupal/mjml_render_engine
drush en mjml_render_engine

Quick Start

1. Create an email theme

Create a theme that uses the twig_mjml engine:

# themes/custom/mail/mail.info.yml
name: 'Mail Theme'
type: theme
description: 'Email theme using MJML templates.'
core_version_requirement: ^11.3
engine: twig_mjml
base theme: false

2. Write MJML templates

Templates use the .html.twig.mjml extension: see README.md example

3. Include and extend other templates

Full Twig inheritance works — include both .html.twig and .html.twig.mjml files: see README.md example

Custom Binary Path

In case you need to use a different binary location, you can override the MJML binary location in settings.php or settings.local.php:

$settings['mjml_render_bin.path'] = '/path/to/custom/mjml';

See the MJML Render Binary project for Docker commands to build custom MJML binaries for any version or platform.

Requirements

• Drupal 11.3.0+ (uses ThemeEngineInterface introduced in 11.3)
• MJML Render Binary (installed automatically as a Composer dependency)

Related Projects

• MJML Render Devel — the UI module for MJML templates development and testing
• MJML Render Binary — the standalone MJML binary package (no Node.js at runtime)
• MJML — the responsive email framework