Advanced Newsletter Suite für Magento 2 - Installations- und Konfigurationsanleitung

Ziel des Dokuments

Dieses Dokument beschreibt die Installation und Konfiguration des Pakets magento-2-package-advanced-newsletter-suite. Es handelt sich um ein vollständiges Newsletter- und E-Mail-Marketing-Paket für Magento 2, das Empfänger, Capture, Kampagnen, Inhalte, Versand, Tracking, ein operatives Panel sowie frontendseitige Anmeldepunkte umfasst.

Voraussetzungen

Bereiten Sie vor der Implementierung Folgendes vor:

• Magento Open Source 2.4.x,
• Composer,
• CLI-Zugriff auf bin/magento,
• ein Magento-Administratorkonto,
• SMTP-Zugangsdaten,
• einen konfigurierten Magento-Cron,
• die Bereitschaft, Queue Consumers auszuführen,
• eine Testumgebung zur Überprüfung von Anmeldung, Kampagnen und Versandvorgängen.

Was das Paket installiert

Das Paket umfasst:

• Kowal_MarketingCore,
• Kowal_EmailTransport,
• Kowal_EmailSmtp,
• Kowal_EmailEvents,
• Kowal_EmailTemplateStudio,
• Kowal_NewsletterAudience,
• Kowal_NewsletterCapture,
• Kowal_NewsletterCampaigns,
• Kowal_NewsletterConsole,
• Kowal_NewsletterFrontend.

Dies ist die höchste Aggregationsebene im Ökosystem der E-Mail-Marketing-Module für Magento.

Installation

1. Installation des Composer-Pakets

composer config repositories.kowal.package.advanced.newsletter.suite vcs https://github.com/kowalco/package-advanced-newsletter-suitecomposer config repositories.kowal.module.email.events vcs https://github.com/kowalco/module-email-eventscomposer config repositories.kowal.module.email.smtp vcs https://github.com/kowalco/module-email-smtpcomposer config repositories.kowal.module.email.template.studio vcs https://github.com/kowalco/module-email-template-studiocomposer config repositories.kowal.module.email.transport vcs https://github.com/kowalco/module-email-transportcomposer config repositories.kowal.module.marketing.core vcs https://github.com/kowalco/module-marketing-corecomposer config repositories.kowal.module.newsletter.audience vcs https://github.com/kowalco/module-newsletter-audiencecomposer config repositories.kowal.module.newsletter.campaigns vcs https://github.com/kowalco/module-newsletter-campaignscomposer config repositories.kowal.module.newsletter.capture vcs https://github.com/kowalco/module-newsletter-capturecomposer config repositories.kowal.module.newsletter.console vcs https://github.com/kowalco/module-newsletter-consolecomposer config repositories.kowal.module.newsletter.frontend vcs https://github.com/kowalco/module-newsletter-frontendcomposer config --global --auth github-oauth.github.com composer require kowal/package-advanced-newsletter-suite

2. Aktivierung der Module in Magento

bin/magento module:enable \ Kowal_MarketingCore \ Kowal_EmailTransport \ Kowal_EmailSmtp \ Kowal_EmailEvents \ Kowal_EmailTemplateStudio \ Kowal_NewsletterAudience \ Kowal_NewsletterCapture \ Kowal_NewsletterCampaigns \ Kowal_NewsletterConsole \ Kowal_NewsletterFrontendbin/magento setup:upgradebin/magento cache:flush

Im Produktionsmodus führen Sie zusätzlich aus:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -f

Konfiguration

1. Administrativer Bereich

Die grundlegende Konfiguration sollte verfügbar sein unter:

Kowal / Email Marketing

Gemäß der Spezifikation werden folgende Einstellungsgruppen erwartet:

• general,
• transport,
• smtp,
• campaigns,
• double_opt_in,
• events.

2. Versandkonfiguration

Konfigurieren Sie zuerst die Grundlagen der Delivery-Ebene:

• Modulaktivität,
• Standard-Transporttyp,
• Versandprotokollierung,
• SMTP-Konto oder SMTP-Konten,
• Nachrichtenrouting,
• Fallback für Backup-Konten, falls verwendet.

Die Implementierung des vollständigen Pakets erfordert weiterhin eine funktionierende SMTP- und Transportebene.

3. Konfiguration von Empfängern und Anmeldungen

Bestätigen Sie anschließend die Konfiguration der Empfängerebene:

• Integration mit newsletter_subscriber,
• Mailinglisten,
• Segmente,
• Abonnementstatus,
• zusätzliche Abonnenten-Metadaten,
• Quellen der Lead-Generierung,
• Marketing-Einwilligungen.

Konfigurieren Sie außerdem den Anmeldeprozess:

• Formulare und Anmeldepunkte,
• Double Opt-in,
• Vorlage der Bestätigungsnachricht,
• Gültigkeitsdauer des Bestätigungstokens.

4. Kampagnenkonfiguration

Legen Sie im Bereich campaigns Folgendes fest:

• batch_size,
• max_retry_count,
• send_rate_limit_per_run,
• watchdog_timeout_minutes.

Das Paket unterstützt:

• Kampagnendefinition,
• Zeitplanung,
• Empfängerwarteschlange,
• Batch-Verarbeitung des Versands,
• Ausführungshistorie von Kampagnen,
• Testsendungen.

5. Konfiguration von Template Studio

Wenn die Implementierung die Arbeit mit Newsletter-Inhalten umfasst, konfigurieren Sie EmailTemplateStudio entsprechend dem MVP-Umfang:

• Arbeit mit nativen Magento-Newsletter-Vorlagen,
• Auswahl von Produktlayouts,
• Speicherung des generierten Abschnitts in der nativen Vorlage,
• Import fertiger Inhalte in die Kampagne.

6. Konfiguration von E-Mail-Ereignissen

Konfigurieren Sie im Bereich events:

• Ereignisverarbeitung,
• Payload-Retention,
• Richtlinie zur Akzeptanz doppelter Events von Providern.

Die Ebene EmailEvents ist für die Observability des Zustellprozesses und die Verknüpfung von Events mit Transportlogs und Kampagnen verantwortlich.

7. Konfiguration des Admin-Panels und des Frontends

Das vollständige Paket umfasst:

• Kowal_NewsletterConsole als operatives Panel,
• Kowal_NewsletterFrontend als Ebene für frontendseitige Formulare und Anmelde-Widgets.

Prüfen Sie nach der Installation:

• die Verfügbarkeit des Dashboards,
• Schnellzugriffe auf Konfiguration und operative Module,
• die Ansicht der letzten Fehler und Sendungen,
• das Vorhandensein von Anmeldeformularen im Shop-Frontend.

Cron und Queue Consumers

Das vollständige Paket erfordert eine funktionierende asynchrone Verarbeitung.

1. Magento-Cron

bin/magento cron:install

Der Cron sollte zuständig sein für:

• Kampagnenplanung,
• Wiederherstellung von Aufgaben,
• operativen Watchdog.

2. Queue Consumers

Die Queue Consumers sollten für die tatsächliche Verarbeitung von Versand-Batches verantwortlich sein. Die Namen der Consumers müssen aus den aktuellen Dateien etc/queue_consumer.xml der implementierten Module übernommen werden.

Stellen Sie in der Produktionsumgebung sicher:

• dass Consumers im Hintergrund ausgeführt werden,
• einen automatischen Start nach einem Serverneustart,
• Fehlermonitoring,
• Fehlerprotokollierung.

Schritte nach der Installation

Führen Sie nach der Implementierung die vollständige Checkliste aus:

1. Konfigurieren und testen Sie das SMTP-Konto.
2. Überprüfen Sie das Nachrichtenrouting.
3. Prüfen Sie die Abonnentenanmeldung und Double Opt-in.
4. Bestätigen Sie die Kompatibilität mit dem nativen Magento-Newsletter.
5. Erstellen Sie eine Testliste oder ein Testsegment.
6. Bereiten Sie eine Testkampagne vor.
7. Führen Sie einen Testversand durch.
8. Prüfen Sie die Kampagnenplanung über Cron.
9. Überprüfen Sie die Queue-Verarbeitung durch Consumers.
10. Bestätigen Sie die Protokollierung von Logs und E-Mail-Ereignissen.
11. Prüfen Sie das Admin-Dashboard.
12. Überprüfen Sie die frontendseitigen Anmeldeformulare und Widgets.

Abnahmetest nach der Implementierung

Das Paket ist korrekt implementiert, wenn:

• die Module korrekt in Magento 2.4.x installiert werden,
• der SMTP-Versand auf Konto- und Routing-Ebene funktioniert,
• die Abonnentenanmeldung mit dem nativen Magento-Newsletter kompatibel bleibt,
• die Kampagne durch cron geplant und durch queue consumer verarbeitet wird,
• Zustellstatus Logs und E-Mail-Ereignisse aktualisieren,
• das Admin-Panel grundlegende operative Daten anzeigt,
• frontendseitige Anmeldepunkte korrekt funktionieren,
• nach Deaktivierung der Module der grundlegende Mechanismus Magento_Newsletter weiterhin funktionieren kann.

Hinweise zur Implementierung

• Das vollständige Paket sollte idealerweise zusammen mit einer bewährten SMTP- und Tracking-Konfiguration implementiert werden.
• Erweiternde Daten sollten in eigenen Tabellen gespeichert werden, ohne die native Tabelle newsletter_subscriber zu duplizieren.
• Die operative Dokumentation der Implementierung sollte zusätzlich das Verfahren zur Handhabung von Queues, Webhooks und Regressionstests der Admin-Konfiguration umfassen.

Amazon SES - Kontoeinrichtung und Konfiguration für die Versandintegration

Ziel des Dokuments

Dieses Dokument beschreibt, wie ein AWS-Konto und der Dienst Amazon SES vorbereitet werden, damit die Versandintegration mit den Modulen dieses Projekts durchgeführt werden kann.

Die Anleitung umfasst:

• die Einrichtung eines AWS-Kontos,
• die Aktivierung von Amazon SES,
• die Verifizierung der Domain und des Absenders,
• den Wechsel aus der Sandbox,
• die Vorbereitung der Zugangsdaten,
• zwei Integrationsvarianten mit Magento:
  • über Amazon SES API,
  • über Amazon SES SMTP.

Wichtiger Hinweis für dieses Projekt

Im Projektcode sind zwei Integrationspfade mit Amazon SES verfügbar:

1. SES API in Kowal_EmailTransport mit dem Transporttyp ses.
2. SES SMTP in Kowal_EmailSmtp mit dem Transporttyp smtp.

Das bedeutet, dass AWS- und SES-Konto einmal vorbereitet werden sollten, die endgültige Anbindung an Magento jedoch von der gewählten Implementierungsvariante abhängt.

Voraussetzungen

Bereiten Sie vor dem Start Folgendes vor:

• eine Domain, von der Nachrichten gesendet werden, z. B. example.com,
• Zugriff auf das DNS dieser Domain,
• eine Absenderadresse, z. B. newsletter@example.com,
• eine Kreditkarte oder eine aktive Zahlungsmethode in AWS,
• eine Entscheidung, in welcher Region SES betrieben werden soll, z. B. eu-central-1 oder us-east-1.

1. Einrichtung eines AWS-Kontos

1. Öffnen Sie das AWS-Panel: https://aws.amazon.com/
2. Erstellen Sie ein AWS-Konto.
3. Aktivieren Sie MFA für das Root-Konto.
4. Verwenden Sie die Zugangsschlüssel des Root-Kontos nicht für die Anwendungsintegration.

Für die Magento-Integration erstellen Sie je nach gewählter Variante einen separaten IAM-Benutzer oder separate SMTP-Zugangsdaten.

2. Aktivierung von Amazon SES

1. Melden Sie sich in der AWS Console an.
2. Öffnen Sie den Dienst Amazon Simple Email Service.
3. Wählen Sie die Region, in der Sie den Versand betreiben möchten.

Das ist wichtig, denn bei SES hat die Region operative Bedeutung:

• Absenderidentitäten werden pro Region verwaltet,
• der Status Sandbox/Production Access gilt pro Region,
• die Magento-Konfigurationsdaten müssen auf dieselbe Region verweisen,
• SMTP-Zugangsdaten in SES sind pro Region eindeutig.

Wenn der Shop international tätig ist, sollte die Zielregion für den jeweiligen Markt oder die gesamte Organisation am besten direkt festgelegt und dann konsequent beibehalten werden.

3. Verifizierung der Domain oder Absenderadresse

Die Best Practice für einen Shop ist die Verifizierung der gesamten Domain und nicht nur einer einzelnen E-Mail-Adresse.

Empfohlene Variante

Verifizieren Sie die Domain, z. B. example.com.

Dadurch:

• können Sie von vielen Adressen dieser Domain senden,
• ist der Wechsel in den Produktionsversand einfacher,
• sind Sie besser auf Kampagnen, Transaktionsmails und mehrere Absender vorbereitet,
• lassen sich mehrere Shops, Sprachen und Marken in einem Ökosystem leichter verwalten.

Schritte

1. Gehen Sie in SES zu Identities.
2. Wählen Sie Create identity.
3. Wählen Sie den Typ Domain.
4. Geben Sie die Versanddomain ein.
5. Aktivieren Sie Easy DKIM, wenn Sie keinen Grund haben, eigene DKIM-Schlüssel zu verwenden.
6. Fügen Sie die von AWS angegebenen DNS-Einträge in Ihre DNS-Zone ein.
7. Warten Sie auf den Status Verified.

Minimaler DNS-Umfang

In der Praxis benötigen Sie mindestens:

• SES-Verifizierungseinträge,
• DKIM-Einträge,
• optional einen Eintrag für Custom MAIL FROM.

4. Wechsel aus der SES-Sandbox

Ein neues SES-Konto arbeitet in der Regel zunächst im Sandbox-Modus.

Das bedeutet unter anderem, dass:

• Sie nur von verifizierten Identitäten senden können,
• auch Empfänger verifiziert sein müssen,
• kein normaler produktiver Versand an Shop-Kunden möglich ist.

Schritte

1. Öffnen Sie in SES das Account dashboard oder den Startbildschirm der Konfiguration.
2. Wählen Sie die Option Request production access.
3. Füllen Sie das Formular entsprechend dem Verwendungszweck des Systems aus:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Beschreiben Sie, dass der Versand aus einem eigenen Magento für einen Online-Shop erfolgt.
5. Senden Sie den Antrag ab.

Vor dem Absenden des Antrags sollte die Domain idealerweise bereits verifiziert sein. Das beschleunigt die Freigabe in der Regel.

5. Konfiguration der Zustellbarkeit

Dies ist kein zwingendes Minimum für den ersten Test, wird aber vor dem Produktivbetrieb dringend empfohlen.

DKIM

Wenn Sie Easy DKIM verwenden, signiert SES Nachrichten nach korrekter DNS-Konfiguration automatisch.

Custom MAIL FROM

Wenn Sie die Kontrolle über den technischen Absender und die Zustellbarkeit verbessern möchten:

1. Öffnen Sie die verifizierte Domain in SES.
2. Konfigurieren Sie Custom MAIL FROM domain, z. B. mail.example.com.
3. Fügen Sie im DNS hinzu:
   • MX-Eintrag,
   • SPF/TXT-Eintrag für MAIL FROM.

Das ist besonders sinnvoll für Shops, die regelmäßiges E-Mail-Marketing betreiben und Probleme mit der Absenderreputation begrenzen möchten.

6. Variante A - Integration über Amazon SES API

Diese Variante verwendet den Transporttyp ses, der in Kowal_EmailTransport verfügbar ist.

Wann diese Variante gewählt werden sollte

Wählen Sie SES API, wenn Sie:

• Amazon SES direkt als Provider nutzen möchten,
• ein Transportkonto vom Typ ses pflegen möchten,
• Nachrichten über Kowal_EmailTransport routen möchten.

6.1. Erstellung eines IAM-Benutzers für den Versand

Verwenden Sie nicht das Root-Konto.

Erstellen Sie einen separaten IAM-Benutzer, z. B.:

• magento-ses-sender

Weisen Sie ihm anschließend eine Richtlinie mit minimalen Versandberechtigungen zu.

Beispiel für eine minimale Richtlinie

{ 'Version': '2012-10-17', 'Statement': [ { 'Effect': 'Allow', 'Action': [ 'ses:SendEmail', 'ses:SendRawEmail' ], 'Resource': '*' } ]}

Falls gewünscht, können Sie sie um den Zugriff auf Limits oder Statistiken erweitern, aber für den Versand selbst ist der obige Umfang der Ausgangspunkt.

6.2. Erstellung von Access Key und Secret Key

1. Öffnen Sie IAM.
2. Gehen Sie zu Users.
3. Öffnen Sie den vorbereiteten Benutzer.
4. Wechseln Sie auf den Reiter Security credentials.
5. Wählen Sie im Bereich Access keys die Option Create access key.
6. Speichern Sie:
   • Access Key ID
   • Secret Access Key

Das Secret wird nur einmal angezeigt. Wenn Sie es verlieren, müssen Sie einen neuen Schlüssel erstellen.

6.3. Für Magento benötigte Daten für die API-Variante

Bereiten Sie für das Transportkonto ses in Magento Folgendes vor:

• provider_region, z. B. eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email optional,
• store_id, wenn das Konto nur für eine bestimmte Store View arbeiten soll.

6.4. Zuordnung im Magento-Panel

In Kowal / Email Marketing:

1. Fügen Sie ein neues Transportkonto hinzu.
2. Stellen Sie ein:
   • Transport Type = Amazon SES,
   • Region = SES-Region,
   • Access Key = IAM-Schlüssel,
   • Secret Key = IAM-Secret.
3. Speichern Sie das Konto.
4. Verknüpfen Sie das Konto mit dem Nachrichtenrouting.
5. Führen Sie einen Testversand aus dem Transportkonto aus.

7. Variante B - Integration über Amazon SES SMTP

Diese Variante nutzt Kowal_EmailSmtp.

Wann diese Variante gewählt werden sollte

Wählen Sie SES SMTP, wenn Sie:

• Amazon SES als SMTP-Quelle implementieren möchten,
• das Paket Advance Email Delivery verwenden,
• ein einfacheres Integrationsmodell auf Magento-Seite beibehalten möchten.

7.1. Erstellung von SMTP-Zugangsdaten in SES

1. Öffnen Sie Amazon SES.
2. Gehen Sie zu SMTP settings.
3. Wählen Sie Create SMTP credentials.
4. AWS führt Sie durch die Erstellung eines IAM-Benutzers für SMTP.
5. Speichern Sie:
   • SMTP username
   • SMTP password

Dies sind keine normalen AWS-Schlüssel. Es handelt sich um separate SMTP-Zugangsdaten für SES.

7.2. SMTP-Endpoint

Für SES verwenden Sie einen Host im Format:

email-smtp..amazonaws.com

Beispiel:

email-smtp.eu-central-1.amazonaws.com

7.3. Port und Verschlüsselung

Die am häufigsten verwendeten Einstellungen:

• Port 587 + STARTTLS,
• oder Port 465 + TLS Wrapper / SSL.

In der Praxis ist für Magento der sicherste Ausgangspunkt:

• Host: email-smtp..amazonaws.com
• Port: 587
• Sicherheit: STARTTLS

7.4. Für Magento benötigte Daten für die SMTP-Variante

Bereiten Sie Folgendes vor:

• SMTP-Host,
• Port,
• Verschlüsselungstyp,
• SMTP-Login,
• SMTP-Passwort,
• eine Absenderadresse, die mit der verified identity in SES übereinstimmt.

7.5. Zuordnung im Magento-Panel

In Kowal / Email Marketing:

1. Stellen Sie im Bereich smtp global ein:
   • enabled = Yes,
   • host = SES-Endpoint,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = Adresse für den Test.
2. Speichern Sie die Konfiguration.
3. Führen Sie Send Test Email aus.

Wenn Sie mehrere Konten oder mehrere Store Views verwenden, können Sie auch ein separates Transportkonto vom Typ smtp mit dedizierten Verbindungsdaten konfigurieren.

8. Was in diesem Projekt gewählt werden sollte

Wählen Sie SES API, wenn:

• Sie Transportkonten vom Typ ses verwenden möchten,
• Sie den Versand pro Konto und Provider routen möchten,
• Sie den Transport weiterentwickeln möchten, ohne alles auf der SMTP-Ebene aufzubauen.

Wählen Sie SES SMTP, wenn:

• Ihnen eine schnellere erste Implementierung wichtig ist,
• Sie SES wie einen externen SMTP-Server behandeln möchten,
• Sie hauptsächlich das auf Kowal_EmailSmtp basierende Delivery-Paket implementieren.

9. Minimale Checkliste vor dem Versandtest

Bestätigen Sie vor dem ersten Test:

1. Das AWS-Konto existiert und hat aktive Abrechnung.
2. Die SES-Region wurde ausgewählt.
3. Die Domain oder Absenderadresse hat den Status Verified.
4. Das SES-Konto hat Production Access oder Sie testen nur unter Sandbox-Bedingungen.
5. DKIM ist konfiguriert.
6. Magento hat korrekte Absenderdaten.
7. Die Integrationsvariante wurde ausgewählt:
   • API,
   • oder SMTP.
8. Die Zugangsdaten wurden sicher gespeichert.
9. Ein Test wurde gesendet und die Zustellung der Nachricht bestätigt.

10. Häufigste Fehler

Konto befindet sich weiterhin in der Sandbox

Symptom:

• Die Nachricht wird nicht an normale Empfänger zugestellt.

Ursache:

• kein Production Access.

Domain ist nicht verifiziert

Symptom:

• Absenderfehler oder Versandablehnung.

Ursache:

• keine verified identity für die Domain oder Absenderadresse.

Falsche Region

Symptom:

• Die Daten sehen korrekt aus, aber der Versand funktioniert weiterhin nicht.

Ursache:

• Die Identität wurde in einer anderen Region verifiziert als der, die von der Integration verwendet wird.

Verwechslung von API-Schlüsseln mit SMTP-Zugangsdaten

Symptom:

• SMTP-Login funktioniert nicht.

Ursache:

• In SMTP wurden IAM-Schlüssel statt SMTP username und SMTP password eingetragen.

Verwendung des Root-Kontos

Symptom:

• keine Sicherheitstrennung und aufwendigere Rotation der Zugangsdaten.

Ursache:

• Die Integration basiert auf Root-Daten statt auf einem separaten IAM-Benutzer oder separaten SMTP-Zugangsdaten.

11. Links zur offiziellen AWS-Dokumentation

• Set up your SES account: https://docs.aws.amazon.com/ses/latest/dg/setting-up.html
• Creating and verifying identities: https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html
• Verified identities: https://docs.aws.amazon.com/ses/latest/dg/verify-addresses-and-domains.html
• Request production access: https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html
• SMTP credentials: https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html
• SMTP endpoint connection: https://docs.aws.amazon.com/ses/latest/dg/smtp-connect.html
• Custom MAIL FROM: https://docs.aws.amazon.com/ses/latest/dg/mail-from.html
• SES regions: https://docs.aws.amazon.com/ses/latest/dg/regions.html
• SES credentials overview: https://docs.aws.amazon.com/ses/latest/dg/send-email-concepts-credentials.html
• IAM access keys: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

12. Daten, die für die Implementierung übergeben werden müssen

Am Ende sollte die Person, die SES einrichtet, genau diesen Datensatz für die Implementierung übergeben:

Für die SES-API-Variante

• SES-Region,
• verified domain,
• access key,
• secret key,
• Absenderadresse,
• reply-to, falls abweichend,
• Information, ob das Konto global oder pro Store View arbeiten soll.

Für die SES-SMTP-Variante

• SES-Region,
• SMTP-Host,
• Port,
• security mode,
• SMTP username,
• SMTP password,
• Absenderadresse,
• Testadresse zur Verifizierung.