Download the PHP package laravel-enso/mails without Composer

Mails

Description

Laravel Enso Mails provides the central email design system for Laravel Enso applications. It ships modern Markdown mail layouts, reusable Blade mail components, brand tokens, and a preview catalog so framework packages and applications can migrate email templates incrementally without copying CSS or layout HTML into every mail.

The package uses MJML only at package build time. Consuming Laravel applications send compiled Blade Markdown mail views at runtime and do not need Node.js or MJML installed to send mail.

Installation

Install the package with Composer:

The service provider is auto-discovered by Laravel. It registers the package views, configures the Laravel Markdown mail paths, registers the built-in preview catalog, and exposes the preview route and command.

Publish the config when an application needs brand overrides:

This publishes:

View publishing is available for deliberate overrides only:

::: warning Note Do not publish views just to customize brand colors, logo, spacing, or font. Use config/enso/mails.php for those values so applications stay on the shared layout and component system. :::

Features

• Central Markdown mail layouts for normal and wide email bodies.
• Compatibility aliases for mail::message, mail::message-wide, mail::transactional, mail::action-required, and mail::report.
• Reusable Blade components for titles, tags, buttons, boxes, alerts, quotes, panels, files, metrics, tables, schedules, dividers, signatures, headers, and footers.
• Brand tokens for logo, name, URL, colors, typography, spacing, radius, footer text, legal text, and footer links.
• MJML source layout compiled into runtime Blade views.
• Runtime mail sending without Node.js or MJML.
• Local preview catalog for browser review.
• Artisan preview command for listing and rendering static HTML previews.
• Built-in boilerplate previews for transactional, action-required, report, metrics, and the full component catalog.
• Preview sections for boilerplates, Enso package-owned mail, and app-specific mail.

Usage

After installation, existing Laravel Markdown mail templates can keep using Laravel's standard mail namespace:

Applications customize the layout through config/enso/mails.php:

The package supports common Laravel Markdown button aliases:

The aliases map to configured Enso color variants:

Preview Catalog

The preview route is enabled outside production by default:

Open the catalog in a browser:

Open a specific preview:

The route is intended for local and staging review. It does not send email; it renders preview views with fake structured data.

Registering Package And Application Previews

Packages and applications can register their own previews through the registry. Package-owned mail previews should live in a dedicated MailServiceProvider and packages that use the shared mail layouts should require laravel-enso/mails directly in composer.json.

Preview data should be fake and structured. Framework previews should not hardcode application-specific brand names, colors, logos, or business logic.

Preview Command

List registered previews:

Render one preview to stdout:

Render every registered preview to static HTML files:

The command is useful for batch QA, static review, and screenshot workflows. Browser review during development usually happens through /enso-mails-preview.

Package Build Flow

MJML is a package development dependency. Maintainers edit:

Then compile the runtime Blade views:

The compiler writes:

Before releasing, verify the compiled Blade views are current:

Consuming applications do not run this build step at runtime.

API

Config

The config namespace is:

Important groups:

• brand: name, URL, logo, logo maximum width and height, and label.
• colors: primary, accent, link, semantic variants, dark, light, and white tokens.
• layout: width, wide width, background, surface, border, radius, card radius, gutter.
• text: font family, spacing, body, muted, heading, and surface colors.
• components: button, box, file, tag, and table defaults.
• footer: footer text, legal text, and links. footer.text accepts a nullable string. A null value renders the localizable This message was sent by :appName. fallback, while an empty string remains empty. Configured footer text is resolved through the active locale at render time; missing translations display it unchanged.
• markdown: Markdown theme and path behavior.
• preview: preview route enablement.

Components

Reusable Markdown components:

• mail::title
• mail::tag
• mail::button
• mail::box
• mail::alert
• mail::quote
• mail::panel
• mail::file
• mail::metric
• mail::table
• mail::schedule
• mail::divider
• mail::signature

mail::file accepts optional url, meta, and icon parameters. When url is present, the whole file pill is rendered as a hyperlink, which is useful for generated exports or downloadable documents.

Layout and compatibility components:

• mail::layout
• mail::header
• mail::footer
• mail::subcopy
• mail::message
• mail::message-wide
• mail::transactional
• mail::action-required
• mail::report

The components preview documents every reusable content component with a short description and a rendered example.

Preview Registry

LaravelEnso\Mails\Preview\PreviewRegistry stores preview definitions.

LaravelEnso\Mails\Preview\PreviewDefinition accepts:

• key: route and command identifier.
• name: human-readable catalog label.
• view: Blade view name.
• data: fake data passed to the view.

Catalog names, section labels, and package-owned boilerplate copy are resolved through the active locale at render time. Their English text acts as the translation key and natural fallback, so applications can translate existing preview names directly in their JSON language files without changing preview registrations.

Commands

Depends On

• PHP ^8.2
• Laravel Framework ^12.0|^13.0
• mjml as a package development dependency for compiling source MJML into runtime Blade views.

Contributions

are welcome. Pull requests are great, but issues are good too.

Thank you to all the people who already contributed to Enso!