Deutsche Version

Back to overview

Newsletter Management: Configuration

This documentation always describes the latest published version.

Everything that controls how the newsletter behaves in your shop is managed in the admin, per channel. Only the button colors used in the plugin's emails live in a configuration file. This page covers the settings, the newsletter categories, the admin lists and the CSV export of subscribers.

Overview: where to find what

The plugin adds exactly one entry to the admin sidebar: MMKreativ Plugins → Newsletter management. It opens the list of newsletter settings. Everything else is reached through buttons in the title bar of that page, and each of those pages has a button in its own title bar that takes you back.

The categories are also listed right below the settings list, with a button to create one. Without a category the signup form offers no choice.

As long as a channel has no settings or "Newsletter enabled" is off, that channel behaves as if the plugin were not installed: the /newsletter page returns 404, the footer form is missing, and Sylius' own newsletter checkbox is left alone. Unsubscribe and manage links in emails that have already been sent keep working.

Settings per channel

These settings are not bundle configuration but database records. There is at most one record per channel. Create it with "Create" on the newsletter settings list and pick the channel there.

When the two purge commands must run and how to set them up as cronjobs is covered on the Installation and operation page. The retention periods only take effect once the commands run regularly.

Sender

The plugin has two mail paths, and both use the channel's sender:

• Confirmation, welcome and "already subscribed" emails go through the Sylius mailer. The sender name is the "Sender name" setting, otherwise the channel name. The sender address is the "Sender email" setting, otherwise the channel's contact email, and finally the default sender from sylius_mailer.
• Newsletters go through the Symfony Mailer. The sender name is "Sender name", otherwise the channel name. The sender address is "Sender email", otherwise the channel's contact email. If both are missing, the newsletter can be neither sent nor test-sent, and the admin tells you so.

Privacy policy link

The consent checkbox of the signup form links to your privacy policy as soon as "Privacy policy page" is set. The link opens in a new tab so a half-filled form is not lost. Three notations are accepted:

A route name that does not exist (renamed, typo) or that needs further parameters produces no link. The signup page still works, and the consent text simply appears without a link. Input in any other form is rejected with a validation error when you save.

Dedicated mailer transport

"Mailer transport for newsletters" separates newsletters from your regular shop mail, for example by sending them through a dedicated delivery provider. Enter the name of a transport from framework.mailer.transports. When sending a newsletter, the plugin sets the X-Transport header, which Symfony Mailer evaluates and removes before delivery.

# config/packages/mailer.yaml
framework:
    mailer:
        transports:
            main: '%env(MAILER_DSN)%'
            newsletter: '%env(MAILER_NEWSLETTER_DSN)%'

Then enter newsletter in the admin under "Mailer transport for newsletters". Without a value, the newsletter uses the default transport.

The transport applies to newsletters only. Confirmation, welcome and "already subscribed" emails keep using your shop's default transport.

Configuration file: button colors in emails

The button in the plugin's emails (confirm, manage subscription) is teal by default. If that does not match your theme, set the colors in a configuration file. This is the plugin's only bundle configuration.

# config/packages/mmd_sylius_newsletter_management.yaml
mmd_sylius_newsletter_management:
    email:
        button_color: '#1663CC'
        button_text_color: '#ffffff'

An invalid color aborts building the container with the message Expected a hex color such as "#1663CC". The plugin reads no environment variables of its own.

Newsletter categories

Categories (for example "New products" or "Tutorials") let subscribers choose the topics they care about. Manage them under Categories or directly below the settings list.

How categories behave:

• The signup form and the page for managing a subscription only offer enabled categories of their own channel. If there are none, no choice is shown and every subscriber gets the general newsletter.
• A subscriber who picks no category gets everything. When you send a newsletter that has categories assigned, it goes to subscribers with at least one matching category and to subscribers without any category. A newsletter without categories goes to every confirmed subscriber of the channel.
• A category restricted to other channels cannot be chosen, not even with a crafted request.

Admin lists

A subscriber's detail page shows, among other things, the source (storefront form, API, registration or admin), language, time and IP address of signup and confirmation, and the time of unsubscribing, as proof of consent. The newsletter list is covered on Writing and sending newsletters.

Subscriber CSV export

The title bar of the subscriber list has two buttons: Export confirmed (CSV) and Export all (CSV). The file is named newsletter-subscribers-YYYY-MM-DD.csv. It is UTF-8 encoded with a BOM so Excel displays umlauts correctly, and uses ; as the separator.

You can narrow the export with URL parameters: /admin/newsletter-subscriptions/export?status=confirmed&channel=de_shop&category=news. status accepts pending, confirmed and unsubscribed (any other value returns error 400), channel the code of a channel, category the code of a category. The admin part of the path is your shop's configured admin path. Cells starting with =, +, - or @ get a leading apostrophe so spreadsheet software does not execute them as formulas.

Practical examples

German shop with double opt-in

A shop with one channel de_shop that runs its newsletter in a privacy-compliant way:

If your shop provides the privacy policy as a route instead (for example shop_legal_datenschutz), enter the route name and the language is taken into account automatically.

Multiple channels with separate senders

A shop runs de_shop and en_shop. Create separate settings for each channel, because sender, privacy page and transport apply per channel:

If you create the category "New products" without selecting a channel, it appears in both channels. If you select only de_shop for the category "Germany only", only that channel offers it. A subscription always belongs to one channel; the same email address can be subscribed separately in both channels.

Personal tracking with consent

You want to know who opens and clicks your newsletter, but only with consent:

The signup form then shows an additional, optional checkbox with this text, separate from the consent to receive the newsletter. The wording is stored with every consent. Subscribers who leave the checkbox unticked still receive the newsletter but are only counted anonymously.

You have to mention any tracking in your privacy policy.