Amazon SES - Kontoerstellung 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 Erstellung eines AWS-Kontos,
• die Aktivierung von Amazon SES,
• die Verifizierung von Domain und Absender,
• den Wechsel aus dem Sandbox-Modus,
• die Vorbereitung der Zugangsdaten,
• zwei Varianten der Integration 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 es sinnvoll ist, AWS- und SES-Konto einmal vorzubereiten, die endgültige Anbindung an Magento jedoch von der gewählten Implementierungsvariante abhängt.

Grundvoraussetzungen

Bereiten Sie vor Beginn 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 Zahlungskarte oder eine aktive Abrechnungsmethode in AWS,
• die Entscheidung, in welcher Region SES betrieben wird, z. B. eu-central-1 oder us-east-1.

1. Erstellung 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 keine Zugangsschlüssel des Root-Kontos für die Anwendungsintegration.

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

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 durchführen möchten.

Das ist wichtig, da die Region in SES eine operative Bedeutung hat:

• 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 arbeitet, sollte die Zielregion für den jeweiligen Markt oder die gesamte Organisation am besten direkt festgelegt und konsequent verwendet werden.

3. Verifizierung der Domain oder der Absenderadresse

Die beste Praxis 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 versenden,
• wird der Übergang zum produktiven Versand erleichtert,
• sind Sie besser auf Kampagnen, Transaktionen 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 Ihrer DNS-Zone hinzu.
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 anfangs in der Regel im Sandbox-Modus.

Das bedeutet unter anderem:

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

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 Ihrem eigenen Magento für einen Online-Shop erfolgt.
5. Senden Sie den Antrag ab.

Vor dem Absenden des Antrags ist es sinnvoll, die Domain bereits verifiziert zu haben. Das beschleunigt in der Regel die Freigabe.

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 dem 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 verwenden möchten,
• Sie ein Transportkonto vom Typ ses verwalten möchten,
• Sie 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 Berechtigungen für den Versand zu.

Beispiel für eine minimale Richtlinie

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

Falls gewünscht, kann sie um das Auslesen von Limits oder Statistiken erweitert werden, für den reinen Versand ist der oben genannte Umfang jedoch ein geeigneter 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 zum Tab Security credentials.
5. Wählen Sie im Abschnitt Access keys die Option Create access key.
6. Speichern Sie:
   • Access Key ID
   • Secret Access Key

Das Secret wird nur einmal angezeigt. Wenn es verloren geht, muss ein neuer Schlüssel erstellt werden.

6.3. Für Magento benötigte Daten der 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 funktionieren 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 auf Ebene des Transportkontos durch.

7. Variante B - Integration über Amazon SES SMTP

Diese Variante verwendet Kowal_EmailSmtp.

Wann diese Variante gewählt werden sollte

Wählen Sie SES SMTP, wenn:

• Sie Amazon SES als SMTP-Quelle implementieren möchten,
• Sie das Paket Advance Email Delivery verwenden,
• Sie 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 gewöhnlichen AWS-Schlüssel. Es handelt sich um separate SMTP-Zugangsdaten für SES.

7.2. SMTP-Endpoint

Verwenden Sie für SES einen Host im Format:

email-smtp..amazonaws.com

Beispiel:

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

7.3. Port und Verschlüsselung

Am häufigsten verwendete 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
• Security: STARTTLS

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

Bereiten Sie 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 Abschnitt smtp global Folgendes 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 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 Delivery-Paket auf Basis von Kowal_EmailSmtp implementieren.

9. Minimale Checkliste vor dem Versandtest

Bestätigen Sie vor dem ersten Test:

1. Das AWS-Konto existiert und die Abrechnung ist aktiv.
2. Die SES-Region wurde ausgewählt.
3. Die Domain oder die 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 verfügt über korrekte Absenderdaten.
7. Die Integrationsvariante wurde gewä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 gesendet.

Ursache:

• kein Production Access.

Domain ist nicht verifiziert

Symptom:

• Absenderfehler oder Versandablehnung.

Ursache:

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

Falsche Region

Symptom:

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

Ursache:

• die Identität ist in einer anderen Region verifiziert als der von der Integration verwendeten.

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:

• fehlende Sicherheitstrennung und erschwerte 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, für die Implementierung genau diesen Satz ü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 funktionieren soll.

Für die SES SMTP-Variante

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

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,
• Zugangsdaten für SMTP,
• einen konfigurierten Magento-Cron,
• Bereitschaft zum Ausführen von Queue Consumers,
• eine Testumgebung zur Prüfung von Anmeldung, Kampagnen und Versand.

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

Die Zugangsdaten zum Composer-Repository, also die E-Mail-Adresse des Kunden und das Lizenz-Token, erhalten Sie nach dem Kauf per E-Mail. Sie sind außerdem nach dem Login im Kundenbereich auf kowal.store verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch das erhaltene Token. Führen Sie die Befehle im Magento-Stammverzeichnis aus.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'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

Führen Sie im Produktionsmodus zusätzlich aus:

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

Konfiguration

1. Administrationsbereich

Die Grundkonfiguration sollte verfügbar sein unter:

Kowal / Email Marketing

Gemäß Spezifikation werden folgende Einstellungsgruppen erwartet:

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

2. Versandkonfiguration

Konfigurieren Sie zunächst die Delivery-Grundlage:

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

Die Implementierung des vollständigen Pakets erfordert weiterhin eine funktionsfähige SMTP- und Transportschicht.

3. Konfiguration von Empfängern und Anmeldungen

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

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

Konfigurieren Sie außerdem den Anmeldeprozess:

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

4. Kampagnenkonfiguration

Legen Sie im Abschnitt campaigns Folgendes fest:

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

Das Paket unterstützt:

• Kampagnendefinition,
• Zeitplan,
• Empfänger-Queue,
• Batching des Versands,
• Ausführungshistorie der Kampagne,
• Testversand.

5. Konfiguration von Template Studio

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

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

6. Konfiguration von E-Mail-Events

Konfigurieren Sie im Abschnitt events Folgendes:

• Event-Verarbeitung,
• Payload-Retention,
• Richtlinie zur Akzeptanz doppelter Events von Anbietern.

Die Schicht EmailEvents ist für die Beobachtbarkeit 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 Schicht für frontendseitige Anmeldeformulare und Widgets.

Überprüfen Sie nach der Installation:

• Verfügbarkeit des Dashboards,
• Shortcuts zur Konfiguration und zu operativen Modulen,
• Ansicht der letzten Fehler und Versandvorgänge,
• 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

Cron sollte verantwortlich sein für:

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

2. Queue Consumers

Queue Consumers sollten für die tatsächliche Verarbeitung der Versand-Batches verantwortlich sein. Die Namen der Consumers sind den aktuellen Dateien etc/queue_consumer.xml der implementierten Module zu entnehmen.

Achten Sie in der Produktionsumgebung auf:

• Ausführung der Consumers im Hintergrund,
• Autostart nach einem Serverneustart,
• Ausfallüberwachung,
• 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 Nachrichten-Routing.
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 Test send aus.
8. Prüfen Sie die Kampagnenplanung über Cron.
9. Überprüfen Sie die Queue-Verarbeitung durch Consumers.
10. Bestätigen Sie die Speicherung von Logs und E-Mail-Events.
11. Prüfen Sie das Administrations-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 über Konten und Routing funktioniert,
• die Abonnentenanmeldung mit dem nativen Magento-Newsletter kompatibel bleibt,
• die Kampagne über cron geplant und durch queue consumer verarbeitet wird,
• Zustellstatus die Logs und E-Mail-Events aktualisieren,
• das Admin-Panel grundlegende operative Daten anzeigt,
• die frontendseitigen Anmeldepunkte korrekt funktionieren,
• nach der Deaktivierung der Module der Basismechanismus Magento_Newsletter weiterhin funktionieren kann.

Implementierungshinweise

• Es empfiehlt sich, das vollständige Paket zusammen mit einer geprüften SMTP- und Tracking-Konfiguration zu implementieren.
• Erweiterungsdaten sollten in eigenen Tabellen gespeichert werden, ohne die native Tabelle newsletter_subscriber zu duplizieren.
• Die operative Implementierungsdokumentation sollte zusätzlich ein Verfahren für die Verwaltung von Queues, Webhooks und Regressionstests der Administrationskonfiguration umfassen.