Amazon SES - Kontoerstellung und Konfiguration für die Versandintegration

Ziel des Dokuments

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

Die Anleitung umfasst:

• Erstellung eines AWS-Kontos,
• Aktivierung von Amazon SES,
• Verifizierung von Domain und Absender,
• Verlassen der Sandbox,
• Vorbereitung von 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 AWS-Konto und SES einmal vorbereitet werden sollten, die endgültige Anbindung an Magento jedoch von der gewählten Implementierungsvariante abhängt.

Vorannahmen

Bereiten Sie vor dem Start Folgendes vor:

• die Domain, von der Nachrichten versendet werden, z. B. example.com,
• Zugriff auf das DNS dieser Domain,
• Absenderadresse, z. B. newsletter@example.com,
• Zahlungskarte oder aktive Abrechnungsmethode in AWS,
• Entscheidung, in welcher Region SES betrieben werden soll, 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 die Zugriffsschlüssel des Root-Kontos nicht für die Anwendungsintegration.

Bereiten Sie für die Magento-Integration einen separaten IAM-Benutzer oder separate SMTP-Zugangsdaten vor, abhängig von der gewählten Variante.

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 aus, in der Sie den Versand betreiben möchten.

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

• Absenderidentitäten werden pro Region verwaltet,
• der Status sandbox/production access gilt für die Region,
• 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 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 mehreren Adressen dieser Domain senden,
• wird der Übergang zum produktiven Versand einfacher,
• bereiten Sie sich besser auf Kampagnen, Transaktionen und mehrere Absender vor,
• lassen sich mehrere Shops, Sprachen und Marken in einem Ökosystem leichter bedienen.

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. Verlassen der SES-Sandbox

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

Das bedeutet unter anderem:

• Sie können nur von verifizierten Identitäten senden,
• auch Empfänger müssen verifiziert sein,
• 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 Zweck des Systems aus:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Beschreiben Sie, dass der Versand aus dem 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 die Genehmigung in der Regel.

5. Konfiguration der Zustellbarkeit

Dies ist kein verpflichtendes 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äßig E-Mail-Marketing betreiben und Probleme mit der Absenderreputation reduzieren möchten.

6. Variante A - Integration über Amazon SES API

Diese Variante nutzt 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,
• 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.

Bereiten Sie einen separaten IAM-Benutzer vor, z. B.:

• magento-ses-sender

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

Beispiel für eine minimale Policy

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

Wenn Sie möchten, können Sie sie um das Lesen von Limits oder Statistiken erweitern, aber für den reinen Versand ist der oben genannte 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. Gehen 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 sehen Sie nur einmal. 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 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 einen bestimmten Store View funktionieren soll.

6.4. Zuordnung zum 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 Versandtest auf Ebene des Transportkontos durch.

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,
• 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

Das sind keine normalen AWS-Schlüssel. Es sind separate SMTP-Zugangsdaten für SES.

7.2. SMTP-Endpunkt

Verwenden Sie für SES den 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
• security: STARTTLS

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

Bereiten Sie vor:

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

7.5. Zuordnung zum Magento-Panel

In Kowal / Email Marketing:

1. Stellen Sie im Abschnitt smtp global ein:
   • enabled = Yes,
   • host = SES-Endpunkt,
   • 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 die SMTP-Schicht zu stützen.

Wählen Sie SES SMTP, wenn:

• Ihnen eine schnellere Erstimplementierung wichtig ist,
• Sie SES wie einen externen SMTP-Server behandeln möchten,
• Sie hauptsächlich ein auf Kowal_EmailSmtp basierendes 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. Domain oder Absenderadresse haben 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 gewählt:
   • API,
   • oder SMTP.
8. Die Zugangsdaten sind sicher gespeichert.
9. Ein Test wurde gesendet und die Zustellung der Nachricht bestätigt.

10. Häufigste Fehler

Das Konto befindet sich weiterhin in der Sandbox

Symptom:

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

Ursache:

• kein production access.

Die Domain ist nicht verifiziert

Symptom:

• Absenderfehler oder Ablehnung des Versands.

Ursache:

• keine verified identity für Domain oder 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 die von der Integration verwendete.

Verwechslung von API-Schlüsseln mit SMTP-Zugangsdaten

Symptom:

• SMTP-Login funktioniert nicht.

Ursache:

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

Verwendung des Root-Kontos

Symptom:

• fehlende Sicherheitstrennung und schwierigere Rotation von Zugangsdaten.

Ursache:

• 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 dieses Set 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 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 ist 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 Frontend-Anmeldepunkte umfasst.

Voraussetzungen

Bereiten Sie vor der Implementierung Folgendes vor:

• Magento Open Source 2.4.x,
• Composer,
• CLI-Zugriff auf bin/magento,
• Magento-Administratorkonto,
• SMTP-Zugangsdaten,
• konfigurierten Magento-Cron,
• Bereitschaft zum Starten von Queue-Consumern,
• 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 der Lizenz-Token, erhalten Sie nach dem Kauf per E-Mail. Sie sind außerdem im Kundenpanel nach der Anmeldung auf kowal.store verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch den erhaltenen Token. Führen Sie die Befehle im Magento-Hauptverzeichnis 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

Im Produktionsmodus führen Sie 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 zuerst die Delivery-Basis:

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

Die Implementierung des vollständigen Pakets erfordert weiterhin eine funktionierende 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 Abonnentenmetadaten,
• Gewinnungsquellen,
• Marketingeinwilligungen.

Konfigurieren Sie außerdem den Anmeldeprozess:

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

4. Kampagnenkonfiguration

Stellen Sie im Abschnitt campaigns Folgendes ein:

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

Das Paket unterstützt:

• Kampagnendefinition,
• Zeitplan,
• Empfängerwarteschlange,
• 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,
• Speicherung des generierten Abschnitts in der nativen Vorlage,
• Import fertiger Inhalte in die Kampagne.

6. Konfiguration von E-Mail-Ereignissen

Konfigurieren Sie im Abschnitt events:

• Ereignisverarbeitung,
• 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 von Administrationspanel und Frontend

Das vollständige Paket umfasst:

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

Prüfen Sie nach der Installation:

• Verfügbarkeit des Dashboards,
• Verknüpfungen zu Konfiguration und operativen Modulen,
• Ansicht der letzten Fehler und Sendungen,
• Vorhandensein von Anmeldeformularen im Shop-Frontend.

Cron und Queue-Consumer

Das vollständige Paket erfordert funktionierende asynchrone Verarbeitung.

1. Magento-Cron

bin/magento cron:install

Cron sollte zuständig sein für:

• Planung von Kampagnen,
• Wiederherstellung von Aufgaben,
• operativen Watchdog.

2. Queue consumers

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

Achten Sie in der Produktionsumgebung auf:

• Ausführung von Consumers im Hintergrund,
• Autostart nach Serverneustart,
• Überwachung von Ausfällen,
• Fehlerprotokollierung.

Schritte nach der Installation

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

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 Test send aus.
8. Prüfen Sie die Kampagnenplanung über Cron.
9. Überprüfen Sie die Verarbeitung der Warteschlange durch Consumers.
10. Bestätigen Sie die Speicherung von Logs und E-Mail-Ereignissen.
11. Prüfen Sie das Administrations-Dashboard.
12. Überprüfen Sie Frontend-Formulare und Anmelde-Widgets.

Abnahmetest nach der Implementierung

Das Paket ist korrekt implementiert, wenn:

• die Module in Magento 2.4.x korrekt installiert werden,
• SMTP-Versand über Konten und Routing 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 Administrationspanel grundlegende operative Daten anzeigt,
• Frontend-Anmeldepunkte korrekt funktionieren,
• nach der Deaktivierung der Module der Basismechanismus Magento_Newsletter weiterhin funktionieren kann.

Hinweise zur Implementierung

• Das vollständige Paket sollte zusammen mit einer geprüften SMTP- und Tracking-Konfiguration implementiert werden.
• Erweiterungsdaten sollten in eigenen Tabellen gespeichert werden, ohne die native Tabelle newsletter_subscriber zu duplizieren.
• Die operative Dokumentation der Implementierung sollte zusätzlich ein Verfahren für Queue-Verarbeitung, Webhooks und Regressionstests der Administrationskonfiguration enthalten.