README

A Neos CMS package for building and managing responsive emails through the Neos backend. It provides a visual email editor with a component-based approach, using MJML under the hood to ensure compatibility across all major email clients.

Features

Visual Email Editing — Create and edit emails directly in the Neos backend using familiar content elements
MJML Rendering — Emails are rendered via MJML, producing responsive HTML that works across all email clients
Reusable Layouts — Define email layouts with header, footer, and global styling that individual emails inherit
Cascading Styles — Global typography, colors, and spacing can be set on the layout level and overridden per component
Content Components — Section, Column, Headline, Text, Image, Button, Divider, and Spacer
Full i18n Support — All labels available in English and German

Requirements

Neos CMS >= 8.3
PHP >= 8.1 (>= 8.2 for local rendering via spatie/mjml-php ^1.3)
Either Node.js >= 20 for local MJML rendering (MJML 5) or an MJML API (see MJML Rendering)

Installation

Install via Composer:

composer require kaufmanndigital/email-editing

Then choose how MJML is rendered.

MJML Rendering

MJML 5 is used for rendering. There are two converter modes:

Local (default)

MJML is compiled on the application server via Node.js using spatie/mjml-php. Install the installer plugin. It requires spatie/mjml-php and runs npm install for it after every composer install / composer update:

composer config allow-plugins.kaufmanndigital/email-editing-installer true
composer require kaufmanndigital/email-editing-installer:^2.0

Without the installer plugin, require spatie/mjml-php:^1.3 and install the mjml npm package yourself, e.g. in the project root (npm install mjml@^5) - Node.js resolves it from there.

API

The compilation is delegated to an HTTP API compatible to the official MJML API (POST {"mjml": "…"} → {"html": "…", "errors": […], …}, HTTP Basic Auth). Node.js is not needed on the application server then. Use either the official API or a self-hosted, compatible server:

KaufmannDigital:
  EmailEditing:
    mjmlRendering:
      converter:
        mode: 'api'
        api:
          url: 'https://api.mjml.io/v1/render'
          applicationId: '%env:MJML_APPLICATION_ID%'
          secretKey: '%env:MJML_SECRET_KEY%'
          timeout: 30   # seconds

Note that the email content is sent to the configured API.

Upgrading from 3.x to 4.0

spatie/mjml-php and kaufmanndigital/email-editing-installer are no longer required. To keep rendering locally, require kaufmanndigital/email-editing-installer:^2.0 in your project (see Local), or switch to the API mode.
Local rendering needs Node.js >= 20 (MJML 5 fails on older versions, e.g. ReadableStream is not defined on Node 16).
MJML 5 is used instead of MJML 4 (spatie/mjml-php ^1.3). For the email components of this package the output is visually identical. Notable changes in MJML 5: <body> is generated by mj-body, so the mj-body background-color is set on the wrapper div and a css-class on <body>; <mj-include> is ignored by default; the minifier changed from html-minifier to htmlnano/cssnano. Check custom MJML/CSS relying on these details.
Use KaufmannDigital\EmailEditing\Service\MjmlConverter::toHtml() instead of calling Spatie\Mjml\Mjml directly, so your code respects the configured converter mode.

Usage

1. Create an Email Layout

In the Neos backend, create an Email Layout document inside an Email Folder. The layout defines:

Header & Footer — Shared content areas rendered on every email using this layout
Global Styling — Default typography (headlines, body text), background colors, button styles, section/column spacing, column vertical alignment

2. Create an Email

Create an Email document and select the desired layout. The email's main content area accepts Sections, which in turn contain Columns with content elements:

Email
└── Section
    ├── Column
    │   ├── Headline
    │   ├── Text
    │   └── Button
    └── Column
        └── Image

3. Available Content Elements

Element	Description
Section	Container with background image/color support
Column	Layout column within a section
Headline	Heading with full typography control
Text	Rich text with bold and link formatting
Image	Image with optional link and width control
Button	Call-to-action with configurable colors
Divider	Horizontal line (solid, dotted, or dashed)
Spacer	Vertical spacing with configurable height

4. Style Inheritance

Styling follows a cascading pattern: Layout → Section → Column → Element. Properties set on the layout (e.g. headline font family) apply globally unless overridden on a specific element.

Extensions

CleverReach Integration

The optional kaufmanndigital/email-editing-cleverreach package adds the ability to send emails directly to CleverReach from the Neos backend.

composer require kaufmanndigital/email-editing-cleverreach

CSS Building

sass --watch Resources/Private/Scss/EmailEditing.scss Resources/Public/Styles/EmailEditing.css

kaufmanndigital / email-editing

Package info

Security

Statistics