README

Sulu bundle to manage mailing lists, subscribe contacts (including via Sulu Forms), and send MJML-based newsletter mails from the admin UI.

Features

Newsletter management with translatable content and double-opt-in templates.
Newsletter subscriptions with confirm/unsubscribe flow and locale-aware subscriptions.
Admin UI resources and lists for newsletters, newsletter mails, and subscriptions.
Newsletter mails can target newsletter subscribers and optionally filter by selected contacts.
MJML + Twig email templates with configurable wrappers/components and optional caching.
Optional form integration via linderp/sulu-form-save-contact-bundle to auto-subscribe contacts.

Requirements

PHP 8.2+
Sulu 2.6+
linderp/sulu-form-save-contact-bundle
linderp/sulu-base-bundle

Installation

Install the bundle:

composer require linderp/sulu-mailing-list-bundle

If you are not using Symfony Flex, add the bundle to config/bundles.php:

return [
    // ...
    Linderp\SuluMailingListBundle\SuluMailingListBundle::class => ['all' => true],
];

config/routes_admin.yaml

SuluMailingListBundle:
    resource: "@SuluMailingListBundle/Resources/config/routes_admin.yml"

config/routes_website.yaml

SuluMailingListBundle:
    resource: "@SuluMailingListBundle/Resources/config/routes.yml"

Configure MJML and sender settings in config/packages/sulu_mailing_list.yaml:

sulu_mailing_list:
  mjml:
    app_id: <api-id>
    secret_key: <secret-key>
    caching: true
    font_images_path: '%kernel.project_dir%/public/mails/fonts'
    default_background_color: '#FFFFFF'
    socials:
      facebook:
      facebookNoShare:
      twitter:
      twitterNoShare:
      x:
      xNoShare:
      google:
      googleNoShare:
      pinterest:
      pinterestNoShare:
      linkedin:
      linkedinNoShare:
      tumblr:
      tumblrNoShare:
      xing:
      xingNoShare:
      github:
      instagram:
      web:
      snapchat:
      youtube:
      vimeo:
      medium:
      soundcloud:
      dribbble:
  no_reply_email: <no-reply-mail>

Add the admin UI assets dependency (admin app):

assets/admin/package.json

"dependencies": {
  "sulu-mailing-list-bundle": "file:../../vendor/linderp/sulu-mailing-list-bundle/Resources/js"
}

Import the admin UI bundle:

assets/admin/app.js

import "sulu-mailing-list-bundle";

Build admin assets:

cd assets/admin
npm run build

Admin UI

The bundle registers admin resources and lists for:

newsletters
newsletters_mails
newsletters_subscriptions
filtered_contacts (used by the newsletter mail contact selector)

Toolbar actions are provided for:

Subscribe / Unsubscribe on newsletter subscription lists.
Send on newsletter mail detail view (disabled if already sent or translations are missing).

Website routes (unsubscribe / confirm)

The website routes are handled by NewsletterWebsiteController:

/{locale}/newsletter/unsubscribe/{newsletterId}/{token}
/{locale}/newsletter/confirm/{newsletterId}/{token}

Both routes redirect to the configured unsubscribe/confirmation pages on the newsletter entity.

Sending newsletters

Mails are sent only once (sent = true after send).
Only confirmed and not-unsubscribed subscriptions are included.
If contacts are selected, subscribers are filtered to those contacts.
Duplicates are removed per contact.

Sulu Forms integration

The bundle provides two dynamic field types:

newsletter (checkbox)
hidden_newsletter

When a form submission is saved via linderp/sulu-form-save-contact-bundle, selected newsletters are attached to the saved contact and handled by the subscription service.

Email templates

MJML + Twig templates live in Resources/views/mails/:

base_email.mjml.twig (base layout)
wrappers/ for layout sections
components/ for individual blocks

Templates are rendered through the MJML API and can be cached via sulu_mailing_list.mjml.caching.

Extending mail editor resources

The mail editor is built from four building blocks: resources, wrappers, contexts, and fields. When you add one, you must wire it in the correct places. The exact locations differ per type.

Where things live:

Resources: form XML in Resources/config/forms/*.xml + type class in Mail/Resource/Types/
Wrappers: XML in Resources/config/mail/wrappers/*.xml + MJML in Resources/views/mails/wrappers/ + type class in Mail/Wrapper/Types/
Contexts: XML in Resources/config/mail/contexts/*.xml + type class in Mail/Context/Types/ (no MJML template)
Fields: XML in Resources/config/mail/types/*.xml + MJML in Resources/views/mails/components/<type>/<type>.mjml.twig + type class in Mail/Field/Types/

Notes:

Keep XML names/keys aligned with the PHP type name and Twig template name.
Update translations in Resources/translations/ if you add new labels.
PHP types are auto-registered via #[AutoconfigureTag(...)] on the corresponding interface (no manual pool registration needed).

Example: add a new field type quote

XML: Resources/config/mail/types/quote.xml

<?xml version="1.0" ?>
<properties xmlns="http://schemas.sulu.io/template/template"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://schemas.sulu.io/template/template http://schemas.sulu.io/template/properties-1.0.xsd">
    <property name="text" type="text_line">
        <meta>
            <title>mailingListMail.props.quote.text</title>
        </meta>
    </property>
</properties>

MJML: Resources/views/mails/components/quote/quote.mjml.twig

<mj-text font-style="italic">{{ item.text }}</mj-text>

PHP type: Mail/Field/Types/QuoteMailFieldType.php

final class QuoteMailFieldType implements MailFieldTypeInterface
{
    public function getConfiguration(): MailFieldTypeConfiguration
    {
        return new MailFieldTypeConfiguration(
            'quote',
            'mailingListMail.types.quote.label',
            __DIR__ . '/../../../Resources/config/mail/types/quote.xml',
            __DIR__ . '/../../../Resources/views/mails/components/quote/quote.mjml.twig'
        );
    }
}

Admin icon PNG generation

The bundle includes a helper script to generate PNGs from Font Awesome solid SVGs, with optional color variants.

Script location: vendor/linderp/sulu-mailing-list-bundle/scripts/generate-fontawesome-pngs.js

Default output folder: icons/ (in the project root, when run from the project root)

Default Font Awesome SVG folder: assets/admin/node_modules/@fortawesome/fontawesome-free/svgs/solid

Additional SVG folder included: vendor/linderp/sulu-mailing-list-bundle/Resources/social (e.g. social brand icons)

Examples (run from the project root):

# Use COLOR_PICKER_COLORS from .env
node vendor/linderp/sulu-mailing-list-bundle/scripts/generate-fontawesome-pngs.js

# Custom output folder
node vendor/linderp/sulu-mailing-list-bundle/scripts/generate-fontawesome-pngs.js --out /path/to/output

# Custom Font Awesome SVG folder
node vendor/linderp/sulu-mailing-list-bundle/scripts/generate-fontawesome-pngs.js --svg-dir /path/to/solid-svgs

# Custom colors (defaults to output in ./icons)
node vendor/linderp/sulu-mailing-list-bundle/scripts/generate-fontawesome-pngs.js "#F7F7F7" "#A6A6A6"

# Custom output + custom colors
node vendor/linderp/sulu-mailing-list-bundle/scripts/generate-fontawesome-pngs.js --out /path/to/output "#F7F7F7" "#A6A6A6"

Notes:

The script reads solid SVGs from assets/admin/node_modules/@fortawesome/fontawesome-free/svgs/solid by default, but you can override with --svg-dir.
It also includes SVGs from Resources/social/ (e.g. facebook.svg, facebook-noshare.svg).
It skips PNGs that already exist, so you can rerun it to resume.
PNGs are named {svg-name}.png and {svg-name}-{color}.png.

Additional Setup

Fonts

To add a font for the admin mail editor, create a class implementing MailFontInterface:

class MomoMailFont implements MailFontInterface
{
    public function getConfiguration(): MailFontConfiguration
    {
        return new MailFontConfiguration(
            '<url to momo.css>', // css file in /public
            'Momo Trust Sans',
            'Momo Trust Sans, sans-serif'
        );
    }
}

To render a selected font as a PNG for clients with limited webfont support, enable it explicitly. The font file referenced by the CSS URL is rasterized by the server-side Imagick extension, and the image is written below the configured public path:

return (new MailFontConfiguration(
    '<url to momo.css>',
    'Momo Trust Sans',
    'Momo Trust Sans, sans-serif'
))->setWebFont(true)->setStrokeWidth(1);

The optional stroke width is measured in output pixels and is configured per font. It defaults to 0, so a webfont only receives a background-colored text outline when setStrokeWidth() is enabled. The outline is centered on the glyph edge. The default background color used for inherit or missing backgrounds can be configured with mjml.default_background_color and defaults to #FFFFFF.

This should be reserved for short decorative text. Live text remains the default because it is accessible and remains available when images are blocked.

Provide the CSS and referenced font files locally below public. The renderer does not fetch remote CSS or font files during mail rendering. Example CSS:

@font-face {
    font-family: 'Momo Trust Sans';
    font-style: normal;
    font-weight: 400;
    src: url(momo-latin.woff2) format('woff2');
    unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}

linderp / sulu-mailing-list-bundle

Maintainers

Package info

Statistics

Security