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
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:

{# themes/custom/mail/templates/email.html.twig.mjml #}
<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-text>Hello {{ name }}</mj-text>
        <mj-text>{{ message }}</mj-text>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>

3. Include and extend other templates

Full Twig inheritance works — include both .html.twig and .html.twig.mjml files:

<mjml>
  <mj-body>
    {% include 'header.html.twig.mjml' %}
    <mj-section>
      <mj-column>
        <mj-text>{{ content }}</mj-text>
      </mj-column>
    </mj-section>
    {% include 'footer.html.twig.mjml' %}
  </mj-body>
</mjml>

Custom Binary Path

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

Related Projects