Laravel Mail MJML

Build responsive transactional e-mails with MJML and Laravel Mailable classes — with Blade inside your templates and <mj-include> partials.

Maintained fork of asahasrabuddhe/laravel-mjml. No application-level RerenderMjml workaround required.

Contents

• Features
• Requirements
• Installation
• Quick start
• Recommended layout
• Usage
• How it works
• Configuration
• Compiler API
• Migrating from the original package
• Quality & testing
• Changelog

Features

• BuildsMjmlMail trait — add MJML to any Illuminate\Mail\Mailable
• Blade in root views and includes — {{ }}, @if, trans(), asset(), config(), nested <mj-include>
• HTML + plain text — text part generated from compiled HTML
• Compile cache — artifacts stored under Laravel’s view.compiled path
• Strict quality bar — Pest, PHPStan level 8, 100% line coverage on src/

Requirements

Installation

composer require bbs-lab/laravel-mail-mjml
npm install --save-dev mjml

Publish configuration (optional):

php artisan vendor:publish --tag="laravel-mail-mjml-config"

The package auto-registers LaravelMjmlServiceProvider. No manual setup beyond the trait on your mailables.

Quick start

1. Trait on your mailable

<?php

namespace App\Mail;

use BBSLab\LaravelMjml\Concerns\BuildsMjmlMail;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;

class WelcomeMail extends Mailable
{
    use BuildsMjmlMail;
    use Queueable;
    use SerializesModels;

    public function __construct(public string $name) {}

    public function envelope(): Envelope
    {
        return new Envelope(subject: 'Welcome');
    }

    public function content(): Content
    {
        return $this->mjmlContentDefinition('mail.welcome', [
            'name' => $this->name,
        ]);
    }
}

2. MJML Blade view — resources/views/mail/welcome.blade.php

<mjml>
    <mj-body>
        <mj-section>
            <mj-column>
                <mj-text>Hello {{ $name }}</mj-text>
            </mj-column>
        </mj-section>
        <mj-include path="../mjml/footer.mjml" />
    </mj-body>
</mjml>

3. Send as usual

Mail::to($user)->send(new WelcomeMail($user->name));

Recommended layout

Structure that works well in production (one Blade shell per mail, reusable MJML partials):

resources/views/mail/
├── welcome.blade.php          # <mjml> shell + <mj-include>
├── backend/
│   └── reset-password.blade.php
└── mjml/
    ├── head.mjml
    ├── header.mjml
    └── footer.mjml            # Blade: trans(), asset(), @if, etc.

Include paths are resolved relative to the view file that contains <mj-include>. From resources/views/mail/backend/reset-password.blade.php:

<mj-include path="../mjml/footer.mjml" />

Nested includes inside a partial (e.g. header.mjml including snippet.mjml) resolve relative to that partial’s directory.

Usage

Laravel 11+ Content API (recommended)

mjmlContentDefinition() compiles the view and returns a Content instance with html and text:

public function content(): Content
{
    return $this->mjmlContentDefinition('mail.welcome', [
        'name' => $this->name,
        'actionUrl' => $this->actionUrl,
    ]);
}

Classic build() / buildView() flow

public function build(): self
{
    return $this
        ->mjml('mail.welcome', ['name' => $this->name])
        ->subject('Welcome');
}

The trait overrides buildView() when mjml() or mjmlContent() was called. Otherwise the default Laravel view behaviour applies.

Raw MJML string

Useful for tests or dynamically built markup:

return $this
    ->mjmlContent('<mjml><mj-body><mj-text>Hi {{ $name }}</mj-text></mj-body></mjml>')
    ->subject('Hi');

Pass data through the mailable’s viewData / constructor as with any Blade view.

Partial with Blade helpers

resources/views/mail/mjml/footer.mjml:

<mj-section>
    <mj-column>
        <mj-image
            src="{{ asset('images/email-footer.png') }}"
            alt="{{ config('app.name') }}" />
        <mj-text>{{ trans('mail.footer.team') }}</mj-text>
        <mj-text>
            @if ($showSignature)
                {{ $signature }}
            @endif
        </mj-text>
    </mj-column>
</mj-section>

With mjml.process_includes_with_blade enabled (default), these directives run before the MJML binary is invoked.

Preview in the browser (optional)

For local preview without sending mail, compile manually:

use BBSLab\LaravelMjml\Mjml\MjmlCompiler;

$html = (new MjmlCompiler(
    view('mail.welcome', ['name' => 'Preview']),
    ['name' => 'Preview'],
))->renderHtml();

return response($html);

How it works

Default pipeline (one Blade pass before MJML):

Blade view on disk (mail/*.blade.php)
        │
        ▼
MjmlIncludeResolver — inline <mj-include> partials (raw, recursive)
        │
        ▼
Single Blade::render() on the assembled MJML
        │
        ▼
MJML CLI → HTML (cached by content hash)
        │
        ▼
Html2Text → plain-text part

This replaces the legacy pattern from the original package: Blade on the root view, MJML native includes (no Blade in partials), then a second Blade pass on the HTML (RerenderMjml). Here, partials are resolved in PHP and Blade runs once on the full document before the binary sees it.

Do not enable process_includes_with_blade and rerender_blade_after_compile together — you would run Blade multiple times without benefit.

Legacy escape hatch: set process_includes_with_blade to false and rerender_blade_after_compile to true to approximate the old HTML rerender workflow (not recommended for new projects).

Configuration

Environment variables map to config/mjml.php:

MJML_AUTO_DETECT_PATH=true
MJML_PATH_TO_BINARY=
MJML_NODE_PATH=node
MJML_PROCESS_INCLUDES_WITH_BLADE=true
MJML_RERENDER_BLADE_AFTER_COMPILE=false

Production tip: set auto_detect_path to false and path_to_binary to a known binary in CI/Docker images where node_modules may not exist at runtime.

Compiler API

For advanced use (custom basePath, mocked process, container binding):

use BBSLab\LaravelMjml\Mjml\MjmlCompiler;

$compiler = app(MjmlCompiler::class, [
    'mjml' => view('mail.welcome', $data),
    'data' => $data,
    'basePath' => resource_path('views/mail'),
]);

$html = $compiler->renderHtml();
$text = $compiler->renderText();

Registered services: MjmlIncludeResolver (singleton), MjmlCompiler (bind).

Migrating from the original package

// Before
use Asahasrabuddhe\LaravelMJML\Mail\Mailable;

// After
use BBSLab\LaravelMjml\Concerns\BuildsMjmlMail;
use Illuminate\Mail\Mailable;

class WelcomeMail extends Mailable
{
    use BuildsMjmlMail;
}

Quality & testing

Current targets on main (local, PHP 8.3+):

Mutation testing uses Pest Mutate. Each test file declares covers() for the classes it exercises. The test-mutation script runs composer clean first, then ensures Pest’s mutate temp directory exists (avoids false-low scores when .temp/mutations is missing).

Contributor workflow:

composer install
composer test              # fast suite (no Node)
npm install                # only for MJML E2E
composer test-mjml           # real mjml CLI → responsive HTML
composer test-coverage
composer test-mutation
composer analyse
composer format
composer clean   # manual wipe; test-mjml / test-coverage / test-mutation already call it

CI runs the Pest Package suite on Ubuntu for each supported Laravel version (11–13) against the PHP versions that Laravel supports (see exclude in run-tests.yml: e.g. no PHP 8.5 on Laravel 11), with prefer-lowest and prefer-stable. run-mjml-e2e-tests uses the same PHP×Laravel matrix (8 jobs, prefer-stable only) with Node 24 and npm ci. Mutation tests run on push/PR when src/ or tests/ change.

Changelog

See CHANGELOG.

Contributing

See CONTRIBUTING.

Security

See SECURITY.

Credits

• BBS
• Ajitem Sahasrabuddhe for the original laravel-mjml package

License

The MIT License (MIT). See LICENSE.