Newsletter Management: Fehlerbehebung und FAQ

Fehlerbehebung für das Newsletter-Plugin für Sylius - fehlende Mails, Cronjob und Versand, Platzhalter, Setup-Kommando, bekannte Einschränkungen und häufige Fragen

English Version

Zurück zur Übersicht

Diese Dokumentation bezieht sich immer auf die aktuellste veröffentlichte Version.

Fehlerbehebung

Symptom: /newsletter antwortet mit 404, die Shop-API-Anmeldung mit 404, oder der Teaser im Footer erscheint nicht.

Check: Öffne im Admin die Newsletter-Einstellungen des betroffenen Channels (Admin-Sidebar → MMKreativ Plugins → Newsletterverwaltung). Ohne Einstellungen für den Channel oder mit ausgeschaltetem Schalter Newsletter aktiv verhält sich das Plugin, als wäre es nicht da: die Seite /newsletter und die Anmeldung über die Shop API antworten mit 404, der Footer bleibt leer. Bestätigungs-, Verwaltungs- und Abmelde-Link bereits angemeldeter Personen funktionieren weiter. Der Footer-Teaser braucht zusätzlich den Schalter Anmeldeformular im Footer. Auf den eigenen Newsletter-Seiten wird er bewusst nicht angezeigt, damit er nicht das Formular doppelt.

Lösung: Schalte den Newsletter für den Channel ein und aktiviere bei Bedarf das Footer-Formular. Achte darauf, den richtigen Channel zu öffnen, denn die Einstellungen gelten pro Channel. Ersetzt dein Theme das Footer-Template, braucht es den Hook sylius_shop.base.footer.content (siehe Storefront-Integration).

Die Bestätigungs-Mail kommt nicht an

Symptom: Nach der Anmeldung zeigt die Seite "Prüfe dein Postfach", aber es kommt keine Mail.

Check:

Wurde dieselbe Adresse in den letzten 10 Minuten schon angemeldet? Mails, die ein öffentliches Formular auslöst, werden pro Adresse gedrosselt, damit niemand ein fremdes Postfach fluten kann. Die Seite antwortet trotzdem normal.
Hat der Channel einen Absender? Er stammt aus den Newsletter-Einstellungen (Absendername / Absender-E-Mail) und fällt auf Channel-Name und Kontakt-E-Mail des Channels zurück.
Schau ins Log: Schlägt der Mail-Versand fehl, bricht die Anmeldung nicht ab (der Zustand ist schon gespeichert), und das Plugin schreibt nur Exception-Klasse und Code ins Log, nie die Adresse.
Ist der Mail-Transport deines Shops korrekt eingerichtet (SPF/DKIM für die Absenderadresse)?

Lösung: Warte die 10 Minuten ab oder korrigiere Absender und Transport. Eine erneute Anmeldung einer noch unbestätigten Adresse verschickt die Bestätigung erneut, die Token bleiben dabei gleich.

Der Bestätigungs-Link liefert 404

Symptom: Der Klick auf den Link in der Bestätigungs-Mail zeigt eine Fehlerseite mit Status 404.

Check: Der Token ist unbekannt oder die Adresse hat sich inzwischen abgemeldet. Häufige Ursachen: Die Adresse hatte sich zwischenzeitlich abgemeldet und danach neu angemeldet (die Anmeldung wird mit neuen Token neu gestartet, der alte Link ist tot), oder der Cleanup-Befehl mmd:newsletter:subscription:purge hat die unbestätigte Anmeldung nach Ablauf der Aufbewahrung (Standard 30 Tage) gelöscht.

Lösung: Die Adresse meldet sich einfach neu an.

Nach "Jetzt senden" geht nichts raus

Symptom: Der Newsletter steht auf Wird versendet, aber es kommen keine Mails an, oder der Fortschritt bewegt sich nicht.

Check: Verschickt wird ausschließlich vom Befehl mmd:newsletter:send, nicht im Admin-Request. Läuft der Cronjob jede Minute? Prüfe außerdem das Versandprotokoll auf der Detailseite des Newsletters auf den Status Fehlgeschlagen und die Fehlermeldung.

Lösung: Richte den Cronjob ein (siehe Installation und Betrieb):

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

Läuft er schon, begrenzen --limit und --delay-ms die Menge pro Lauf. Überlappende Läufe sind sicher, denn jede Zustellung wird atomar reserviert. Ein Lauf, der abstürzt, hinterlässt eine reservierte Zustellung; sie wird nach 15 Minuten freigegeben und beim nächsten Lauf erneut versucht.

Zustellungen stehen auf "Fehlgeschlagen"

Symptom: Im Versandprotokoll stehen einzelne Empfänger auf Fehlgeschlagen.

Check: Eine fehlgeschlagene Mail wird bei den nächsten Läufen noch bis zu 3 Versuche insgesamt wiederholt. Danach bleibt sie Fehlgeschlagen. Das Versandprotokoll zeigt den letzten Fehler mit Exception-Klasse und Code (nie die Adresse). Typische Ursachen: der Transport lehnt ab, das Limit des Hosts ist erreicht, die Adresse ist ungültig.

Lösung: Behebe die Ursache am Transport. Nutze für Newsletter einen eigenen Transport (Mailer-Transport für Newsletter in den Channel-Einstellungen), damit ein Massenversand weder den Transport für Bestell-Mails ausreizt noch dessen Ruf beschädigt. Mit --delay-ms drosselst du das Tempo, falls dein Host Raten begrenzt.

Symptom: Beim Speichern mit Status Bereit erscheint ein Fehler, oder die Aktionen zum Versenden fehlen.

Check: Zum Status Bereit gehören HTML- und Text-Version, und beide müssen {{ manage_url }} und {{ unsubscribe_url }} enthalten. Ein unbekannter Platzhalter (zum Beispiel ein Tippfehler wie {{ frist_name }}) wird schon beim Speichern abgelehnt. Außerdem müssen die gewählten Kategorien im Channel des Newsletters angeboten werden. Versenden oder Planen scheitert, wenn der Channel keine Absenderadresse hat, keine bestätigten Empfänger vorhanden sind oder (beim Planen) die Zeit in der Vergangenheit liegt.

Lösung: Ergänze die beiden Pflicht-Platzhalter in beiden Versionen und korrigiere unbekannte Platzhalter. Die erlaubten Platzhalter stehen auf der Seite Newsletter.

Ein Link-Scanner meldet Abonnenten ab?

Symptom: Du befürchtest, dass Mail-Scanner den Abmelde-Link aufrufen und Leute ungewollt abmelden.

Check: Das passiert nicht. Der Aufruf des Links per GET zeigt nur eine Seite mit einem Button. Abgemeldet wird ausschließlich durch den POST dieses Buttons.

Lösung: Nichts zu tun. Beim Entwickeln eigener Mail-Vorlagen darfst du diesen Mechanismus nicht umgehen.

Öffnungs- oder Klickraten liegen über 100 Prozent

Symptom: Die Statistik eines Newsletters zeigt mehr als 100 Prozent Öffnungen oder Klicks.

Check: Das anonyme Tracking zählt Aufrufe, nicht Personen. Öffnet jemand die Mail mehrmals, zählt jeder Aufruf. Zusätzlich laden Mail-Programme und Datenschutz-Proxys das Zählpixel oft von selbst, sodass die Öffnungen nur ein grober Richtwert sind.

Lösung: Lies die Werte als Aufrufe pro Zustellung. Eindeutige Raten gibt es nur im Modus Personenbezogen, und dort nur für die Abonnenten, die dem Tracking zugestimmt haben. Details stehen unter Tracking und Statistiken.

Das Setup-Kommando bricht ab

Symptom: bin/console mmd:newsletter-management:setup meldet einen Fehler.

Check und Lösung:

Meldung	Bedeutung	Lösung
"Migrations this plugin builds on are still open"	Migrationen von Sylius oder deiner App sind noch offen	Führe erst `bin/console doctrine:migrations:migrate` aus, dann das Setup erneut
"The migrations of this plugin are not registered with Doctrine"	Das Bundle ist nicht aktiviert oder `sylius_core.prepend_doctrine_migrations` steht auf `false`	Prüfe `config/bundles.php` und die Sylius-Konfiguration
Hinweis, die Routen seien nicht importiert	Die Routen-Imports fehlen	Lege die ausgegebenen Zeilen in einer Datei unter `config/routes/` an. Das Kommando schreibt nie in `config/`

Bekannte Einschränkungen

Die Bestätigungs-Mail verlinkt auf die Storefront-Seite. Ein reiner Headless-Shop muss diesen Link in der Mail-Vorlage auf sein eigenes Frontend umschreiben und den Token an die Shop API senden.
Die Shop-API-Registrierung des Sylius-Kerns (POST /shop/customers) setzt das Kern-Flag ohne Event. Headless-Clients melden sich über POST /shop/newsletter-subscriptions an.
Der Absender der Mails ist standardmäßig die Kontakt-E-Mail des Channels. Weicht sie vom SMTP-Konto deines Shops ab, muss der Mailserver diese Absenderadresse zulassen (SPF/DKIM).
Der CSV-Export hat in der Oberfläche keine Auswahl für Kategorie oder Channel. Die Buttons exportieren alle oder nur die bestätigten Abonnenten; der Endpunkt /admin/newsletter-subscriptions/export akzeptiert zusätzlich ?status=, ?channel=<Code> und ?category=<Code>.
Eine weitergeleitete Mail trägt die Markierung des Weiterleitenden, im Modus Personenbezogen werden ihre Öffnungen daher ihm zugerechnet.

FAQ

Allgemein

Muss ich den Cronjob einrichten?
Ja. Ohne mmd:newsletter:send geht kein Newsletter raus, auch nicht nach "Jetzt senden". Die beiden Cleanup-Befehle (mmd:newsletter:subscription:purge, mmd:newsletter:tracking:purge) laufen täglich.

Kann ein Abonnent seine E-Mail-Adresse ändern?
Nein. Auf der Verwalten-Seite ändern sich nur Name und Kategorien. Eine andere Adresse meldet sich neu an und die alte ab.

Bekommt jemand einen Newsletter, der sich abgemeldet hat?
Nein. Wer zwischen dem Start eines Versands und der Zustellung abbestellt, wird übersprungen.

Verrät das Formular, wer auf der Liste steht?
Nein. Eine bereits bestätigte Adresse bekommt dieselbe Antwort wie eine neue; der Inhaber erhält stattdessen eine "bereits angemeldet"-Mail.

Konfiguration

Gelten die Einstellungen global?
Nein, pro Channel. Jeder Channel hat eigenen Schalter, Double Opt-in, Absender, Aufbewahrungsfristen und Tracking-Modus.

Was passiert bei ausgeschaltetem Double Opt-in?
Die Anmeldung gilt sofort als bestätigt und der Abonnent bekommt direkt die Willkommens-Mail.

Welche Kategorie bekommt jemand, der keine wählt?
Keine Auswahl bedeutet den allgemeinen Newsletter, also alles.

Wie lange werden Daten aufbewahrt?
Abgemeldete Abonnements standardmäßig 1095 Tage, unbestätigte 30 Tage, anonyme Tracking-Zähler 365 Tage, persönliche Tracking-Ereignisse 90 Tage. Alle Werte stellst du pro Channel ein, --older-than=<Tage> überschreibt sie bei den Purge-Befehlen. Bestätigte Abonnements löscht kein Befehl.

Kompatibilität

Welche Versionen unterstützt das Plugin?
Sylius ^2.2, PHP ^8.3 und Symfony ^7.4. Für die Shop API wird API Platform in Version ^4.2.1 oder ^5.0 verwendet.

Funktioniert es mit PostgreSQL?
Nicht getestet. Die Migrationen enthalten MySQL-DDL (zum Beispiel ENGINE = InnoDB) und laufen auf PostgreSQL voraussichtlich nicht.

Läuft es mit Spam-Schutz zusammen?
Ja, das ALTCHA-Plugin schützt Anmeldeseite und Shop API automatisch, sobald du das Schutzziel newsletter in den ALTCHA-Channel-Einstellungen aktivierst, siehe Erweiterbarkeit.