Newsletter Management: Troubleshooting and FAQ

Troubleshooting for the newsletter plugin for Sylius - missing mails, cron job and sending, placeholders, setup command, known limitations and frequently asked questions

Deutsche Version

Back to overview

This documentation always describes the latest published version.

Troubleshooting

Symptom: /newsletter answers 404, signing up through the Shop API answers 404, or the teaser in the footer does not appear.

Check: In the admin, open the newsletter settings of the affected channel (Admin sidebar → MMKreativ Plugins → Newsletter management). Without settings for the channel, or with the Newsletter enabled switch off, the plugin behaves as if it were not there: the /newsletter page and signup through the Shop API answer 404 and the footer stays empty. Confirmation, manage and unsubscribe links of people who are already subscribed keep working. The footer teaser also needs the Signup form in the footer switch. It is deliberately not shown on the plugin's own newsletter pages, where it would duplicate the form.

Solution: Enable the newsletter for the channel and turn on the footer form if you want it. Make sure you open the right channel, since the settings apply per channel. If your theme replaces the footer template, it needs the hook sylius_shop.base.footer.content (see Storefront integration).

The confirmation mail does not arrive

Symptom: After signing up, the page says to check the inbox, but no mail arrives.

Check:

Was the same address already signed up within the last 10 minutes? Mails triggered by a public form are throttled per address so nobody can flood a stranger's inbox. The page still answers normally.
Does the channel have a sender? It comes from the newsletter settings (Sender name / Sender email) and falls back to the channel name and the channel's contact e-mail.
Check the log: if sending the mail fails, the signup does not fail (the state is already stored), and the plugin logs only the exception class and code, never the address.
Is your shop's mail transport set up correctly (SPF/DKIM for the sender address)?

Solution: Wait out the 10 minutes or fix sender and transport. Signing up an address that is still unconfirmed again resends the confirmation; the tokens stay the same.

The confirmation link returns 404

Symptom: Clicking the link in the confirmation mail shows an error page with status 404.

Check: The token is unknown, or the address has unsubscribed in the meantime. Common causes: the address had unsubscribed in the meantime and signed up again (the signup is restarted with new tokens, the old link is dead), or the cleanup command mmd:newsletter:subscription:purge deleted the unconfirmed signup after the retention expired (default 30 days).

Solution: The address simply signs up again.

Nothing goes out after "Send now"

Symptom: The newsletter is in status Sending, but no mails arrive, or the progress does not move.

Check: Mails are sent only by the mmd:newsletter:send command, not in the admin request. Is the cron job running every minute? Also check the delivery log on the newsletter's detail page for the status failed and the error.

Solution: Set up the cron job (see Installation and operation):

* * * * * cd /path/to/shop && php bin/console mmd:newsletter:send --limit=100

If it already runs, --limit and --delay-ms cap the volume per run. Overlapping runs are safe because every delivery is reserved atomically. A run that crashes leaves a reserved delivery behind; it is released after 15 minutes and tried again on the next run.

Deliveries are marked "failed"

Symptom: Individual recipients show failed in the delivery log.

Check: A failed mail is retried on the next runs, up to 3 attempts in total. After that it stays failed. The delivery log shows the last error with exception class and code (never the address). Typical causes: the transport refuses, the host's limit is reached, the address is invalid.

Solution: Fix the cause at the transport. Use a dedicated transport for newsletters (Mailer transport for newsletters in the channel settings), so a bulk send neither exhausts the transport for order mails nor damages its reputation. Use --delay-ms to slow the pace if your host limits rates.

Symptom: Saving with the status ready shows an error, or the send actions are missing.

Check: The status ready requires an HTML and a text version, and both must contain {{ manage_url }} and {{ unsubscribe_url }}. An unknown placeholder (for example a typo such as {{ frist_name }}) is rejected when you save. The selected categories must also be offered in the newsletter's channel. Sending or scheduling fails if the channel has no sender address, there are no confirmed recipients, or (when scheduling) the time is in the past.

Solution: Add the two required placeholders to both versions and fix unknown placeholders. The allowed placeholders are listed on the Newsletters page.

Does a link scanner unsubscribe subscribers?

Symptom: You worry that mail scanners call the unsubscribe link and unsubscribe people unintentionally.

Check: That does not happen. Opening the link with GET only shows a page with a button. Unsubscribing happens only through the POST of that button.

Solution: Nothing to do. When you build your own mail templates, do not bypass this mechanism.

Open or click rates are above 100 percent

Symptom: A newsletter's statistics show more than 100 percent opens or clicks.

Check: Anonymous tracking counts hits, not people. If someone opens the mail several times, every hit counts. Mail programs and privacy proxies also often load the counting pixel on their own, so opens are only a rough indication.

Solution: Read the values as hits per delivery. Unique rates exist only in Personal mode, and there only for the subscribers who agreed to tracking. Details are under Tracking and statistics.

The setup command aborts

Symptom: bin/console mmd:newsletter-management:setup reports an error.

Check and solution:

Message	Meaning	Solution
"Migrations this plugin builds on are still open"	Migrations of Sylius or your app are still pending	Run `bin/console doctrine:migrations:migrate` first, then the setup again
"The migrations of this plugin are not registered with Doctrine"	The bundle is not enabled or `sylius_core.prepend_doctrine_migrations` is set to `false`	Check `config/bundles.php` and the Sylius configuration
Note that the routes are not imported	The route imports are missing	Put the printed lines into a file under `config/routes/`. The command never writes to `config/`

Known limitations

The confirmation mail links to the storefront page. A purely headless shop has to rewrite that link in the mail template to its own frontend and send the token to the Shop API.
Sylius core's Shop API registration (POST /shop/customers) sets the core flag without an event. Headless clients sign up through POST /shop/newsletter-subscriptions.
The mails' sender defaults to the channel's contact e-mail. If it differs from your shop's SMTP account, the mail server has to allow that sender address (SPF/DKIM).
The CSV export has no category or channel picker in the interface. The buttons export all subscribers or only the confirmed ones; the endpoint /admin/newsletter-subscriptions/export additionally accepts ?status=, ?channel=<code> and ?category=<code>.
A forwarded mail carries the forwarder's marker, so in Personal mode its opens are attributed to them.

FAQ

General

Do I have to set up the cron job?
Yes. Without mmd:newsletter:send no newsletter goes out, not even after "Send now". The two cleanup commands (mmd:newsletter:subscription:purge, mmd:newsletter:tracking:purge) run daily.

Can a subscriber change their e-mail address?
No. On the manage page only name and categories change. A different address signs up anew and the old one unsubscribes.

Does someone who unsubscribed still receive a newsletter?
No. Anyone who unsubscribes between the start of a send and the delivery is skipped.

Does the form reveal who is on the list?
No. An already confirmed address gets the same answer as a new one; its owner receives an "already subscribed" mail instead.

Configuration

Are the settings global?
No, they are per channel. Each channel has its own switch, double opt-in, sender, retention periods and tracking mode.

What happens with double opt-in turned off?
The signup counts as confirmed immediately and the subscriber gets the welcome mail right away.

Which category does someone get who picks none?
No selection means the general newsletter, i.e. everything.

How long is data kept?
Unsubscribed subscriptions 1095 days by default, unconfirmed ones 30 days, anonymous tracking counters 365 days, personal tracking events 90 days. You set all values per channel, and --older-than=<days> overrides them for the purge commands. No command deletes confirmed subscriptions.

Compatibility

Which versions does the plugin support?
Sylius ^2.2, PHP ^8.3 and Symfony ^7.4. The Shop API uses API Platform in version ^4.2.1 or ^5.0.

Does it work with PostgreSQL?
Not tested. The migrations contain MySQL DDL (for example ENGINE = InnoDB) and will probably not run on PostgreSQL.

Does it work together with spam protection?
Yes, the ALTCHA plugin protects the signup page and the Shop API automatically once you enable the newsletter protection target in the ALTCHA channel settings, see Extending.