Advanced Newsletter Suite voor Magento 2 - installatie- en configuratiehandleiding

Doel van het document

Dit document beschrijft de installatie en configuratie van het pakket magento-2-package-advanced-newsletter-suite. Het is een volledig nieuwsbrief- en emailmarketingpakket voor Magento 2, inclusief doelgroepen, capture, campagnes, content, verzending, tracking, een operationeel paneel en frontend-inschrijfpunt(en).

Vereisten

Bereid vóór de implementatie het volgende voor:

• Magento Open Source 2.4.x,
• Composer,
• CLI-toegang tot bin/magento,
• een Magento-beheerdersaccount,
• toegangsgegevens voor SMTP,
• een geconfigureerde Magento-cron,
• gereedheid om queue consumers uit te voeren,
• een testomgeving om inschrijving, campagnes en verzendingen te controleren.

Wat het pakket installeert

Het pakket omvat:

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

Dit is het hoogste aggregatieniveau binnen het ecosysteem van emailmarketingmodules voor Magento.

Installatie

1. Installatie van het Composer-pakket

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. Modules activeren 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

Voer in productiemodus bovendien het volgende uit:

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

Configuratie

1. Beheersectie

De basisconfiguratie moet beschikbaar zijn in:

Kowal / Email Marketing

Volgens de specificatie worden de volgende instellingen verwacht:

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

2. Configuratie van verzending

Configureer eerst de basis van delivery:

• moduleactiviteit,
• standaard transporttype,
• logging van verzendingen,
• SMTP-account of SMTP-accounts,
• berichtrouting,
• fallback voor reserveaccounts, indien gebruikt.

De implementatie van het volledige pakket vereist nog steeds een goed werkende SMTP- en transportlaag.

3. Configuratie van doelgroepen en inschrijvingen

Bevestig vervolgens de configuratie van de doelgroeplaag:

• integratie met newsletter_subscriber,
• mailinglijsten,
• segmenten,
• abonnementsstatussen,
• aanvullende abonnee-metadata,
• herkomstbronnen,
• marketingtoestemmingen.

Configureer ook het inschrijfproces:

• formulieren en inschrijfpunt(en),
• double opt-in,
• template voor het bevestigingsbericht,
• geldigheidsduur van de bevestigingstoken.

4. Configuratie van campagnes

Stel in de sectie campaigns het volgende in:

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

Het pakket ondersteunt:

• campagnedefinitie,
• planning,
• ontvangersqueue,
• batching van verzendingen,
• uitvoeringsgeschiedenis van campagnes,
• testverzendingen.

5. Configuratie van Template Studio

Als de implementatie het werken met nieuwsbriefcontent omvat, configureer dan EmailTemplateStudio volgens de MVP-scope:

• werken met native nieuwsbrieftemplates van Magento,
• selectie van productlayouts,
• opslaan van de gegenereerde sectie in de native template,
• import van kant-en-klare content naar de campagne.

6. Configuratie van emailgebeurtenissen

Configureer in de sectie events het volgende:

• verwerking van gebeurtenissen,
• payloadretentie,
• beleid voor het accepteren van dubbele events van providers.

De laag EmailEvents is verantwoordelijk voor observability van het afleverproces en de koppeling van events aan transportlogs en campagnes.

7. Configuratie van het beheerpaneel en frontend

Het volledige pakket omvat:

• Kowal_NewsletterConsole als operationeel paneel,
• Kowal_NewsletterFrontend als laag voor frontendformulieren en inschrijfwidgets.

Controleer na installatie:

• beschikbaarheid van het dashboard,
• snelkoppelingen naar configuratie en operationele modules,
• weergave van recente fouten en verzendingen,
• aanwezigheid van inschrijfformulieren op de frontend van de webshop.

Cron en queue consumers

Het volledige pakket vereist werkende asynchrone verwerking.

1. Magento-cron

bin/magento cron:install

Cron moet verantwoordelijk zijn voor:

• campagneplanning,
• herstel van taken,
• operationele watchdog.

2. Queue consumers

Queue consumers moeten verantwoordelijk zijn voor de daadwerkelijke verwerking van verzendbatches. De namen van consumers moeten worden overgenomen uit de actuele bestanden etc/queue_consumer.xml van de geïmplementeerde modules.

Zorg in de productieomgeving voor:

• het uitvoeren van consumers op de achtergrond,
• autostart na een serverherstart,
• storingsmonitoring,
• foutenlogging.

Stappen na installatie

Voer na de implementatie de volledige checklist uit:

1. Configureer en test het SMTP-account.
2. Controleer de berichtrouting.
3. Test de abonnee-inschrijving en double opt-in.
4. Bevestig compatibiliteit met de native Magento-nieuwsbrief.
5. Maak een testlijst of testsegment aan.
6. Bereid een testcampagne voor.
7. Voer een test send uit.
8. Controleer de campagneplanning via cron.
9. Verifieer queueverwerking door consumers.
10. Bevestig logging van logs en emailgebeurtenissen.
11. Controleer het beheerdashboard.
12. Controleer frontend-inschrijfformulieren en widgets.

Acceptatietest na implementatie

Het pakket is correct geïmplementeerd als:

• de modules correct worden geïnstalleerd in Magento 2.4.x,
• SMTP-verzending werkt via accounts en routing,
• abonnee-inschrijving compatibel blijft met de native Magento-nieuwsbrief,
• de campagne wordt gepland door cron en verwerkt door queue consumer,
• afleverstatussen logs en emailgebeurtenissen bijwerken,
• het beheerpaneel basis operationele gegevens toont,
• frontend-inschrijfpunt(en) correct werken,
• na uitschakeling van de modules het basismechanisme Magento_Newsletter nog steeds kan werken.

Implementatie-opmerkingen

• Het volledige pakket kan het best worden geïmplementeerd samen met een bewezen SMTP- en trackingconfiguratie.
• Uitbreidende gegevens moeten in eigen tabellen worden opgeslagen, zonder duplicatie van de native tabel newsletter_subscriber.
• De operationele documentatie van de implementatie moet daarnaast een procedure omvatten voor de afhandeling van queues, webhooks en regressietests van de beheerconfiguratie.

Amazon SES - account aanmaken en configuratie voor verzendintegratie

Doel van het document

Dit document beschrijft hoe u een AWS-account en de Amazon SES-service voorbereidt zodat de verzendintegratie met de modules van dit project kan worden uitgevoerd.

De handleiding omvat:

• het aanmaken van een AWS-account,
• het activeren van Amazon SES,
• verificatie van domein en afzender,
• het verlaten van de sandbox,
• het voorbereiden van inloggegevens,
• twee integratievarianten met Magento:
  • via Amazon SES API,
  • via Amazon SES SMTP.

Belangrijke opmerking voor dit project

In de projectcode zijn twee integratiepaden met Amazon SES beschikbaar:

1. SES API in Kowal_EmailTransport met transporttype ses.
2. SES SMTP in Kowal_EmailSmtp met transporttype smtp.

Dit betekent dat het AWS- en SES-account het best één keer wordt voorbereid, maar dat de uiteindelijke koppeling met Magento afhangt van de gekozen implementatievariant.

Uitgangspunten

Bereid voor u begint het volgende voor:

• het domein waarvan berichten worden verzonden, bijvoorbeeld example.com,
• toegang tot de DNS van dit domein,
• een afzenderadres, bijvoorbeeld newsletter@example.com,
• een betaalkaart of actieve betaalmethode in AWS,
• de keuze in welke regio SES zal werken, bijvoorbeeld eu-central-1 of us-east-1.

1. Een AWS-account aanmaken

1. Ga naar het AWS-paneel: https://aws.amazon.com/
2. Maak een AWS-account aan.
3. Schakel MFA in voor het root-account.
4. Gebruik geen access keys van het root-account voor applicatie-integratie.

Bereid voor de Magento-integratie een afzonderlijke IAM-gebruiker of afzonderlijke SMTP-inloggegevens voor, afhankelijk van de gekozen variant.

2. Amazon SES activeren

1. Log in op de AWS Console.
2. Open de service Amazon Simple Email Service.
3. Selecteer de regio waarin u verzending wilt uitvoeren.

Dit is belangrijk, omdat de regio in SES operationele betekenis heeft:

• afzenderidentiteiten worden per regio beheerd,
• de sandbox/production access-status geldt per regio,
• de configuratiegegevens in Magento moeten naar dezelfde regio verwijzen,
• SMTP-inloggegevens in SES zijn uniek per regio.

Als de webshop internationaal opereert, is het het best om meteen de doelregio voor een specifieke markt of de hele organisatie vast te leggen en die consequent te gebruiken.

3. Verificatie van domein of afzenderadres

De beste praktijk voor een webshop is verificatie van het volledige domein en niet alleen van één afzonderlijk emailadres.

Aanbevolen variant

Verifieer het domein, bijvoorbeeld example.com.

Daardoor:

• kunt u vanaf meerdere adressen van dit domein verzenden,
• wordt de overstap naar productie eenvoudiger,
• bereidt u zich beter voor op campagnes, transacties en meerdere afzenders,
• wordt het eenvoudiger om meerdere webshops, talen en merken binnen één ecosysteem te ondersteunen.

Stappen

1. Ga in SES naar Identities.
2. Kies Create identity.
3. Kies het type Domain.
4. Voer het verzenddomein in.
5. Schakel Easy DKIM in als u geen reden hebt om uw eigen DKIM-sleutels te gebruiken.
6. Voeg de DNS-records die AWS aangeeft toe aan uw DNS-zone.
7. Wacht op de status Verified.

Minimale DNS-scope

In de praktijk hebt u ten minste het volgende nodig:

• SES-verificatierecords,
• DKIM-records,
• optioneel een record voor custom MAIL FROM.

4. Uit de SES-sandbox gaan

Een nieuw SES-account werkt meestal in eerste instantie in sandbox-modus.

Dat betekent onder andere dat:

• u alleen kunt verzenden vanaf geverifieerde identiteiten,
• ontvangers ook geverifieerd moeten zijn,
• u geen normale productie-uitgaande mail naar webshopklanten kunt uitvoeren.

Stappen

1. Open in SES het Account dashboard of het startscherm voor configuratie.
2. Kies de optie Request production access.
3. Vul het formulier in volgens het gebruiksdoel van het systeem:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Beschrijf dat verzending wordt uitgevoerd vanuit uw eigen Magento voor een online winkel.
5. Dien de aanvraag in.

Voordat u de aanvraag indient, is het verstandig om het domein al te hebben geverifieerd. Dat versnelt de goedkeuring meestal.

5. Configuratie van deliverability

Dit is niet het verplichte minimum voor de eerste test, maar het wordt sterk aanbevolen vóór productie.

DKIM

Als u Easy DKIM gebruikt, ondertekent SES berichten automatisch na correcte DNS-configuratie.

Custom MAIL FROM

Als u de controle over de technische afzender en deliverability wilt verbeteren:

1. Open het geverifieerde domein in SES.
2. Configureer Custom MAIL FROM domain, bijvoorbeeld mail.example.com.
3. Voeg toe aan DNS:
   • een MX-record,
   • een SPF/TXT-record voor MAIL FROM.

Dit is met name zinvol voor webshops die regelmatig emailmarketing uitvoeren en problemen met afzenderreputatie willen beperken.

6. Variant A - integratie via Amazon SES API

Deze variant gebruikt het transporttype ses dat beschikbaar is in Kowal_EmailTransport.

Wanneer kiest u voor deze variant

Kies SES API als u:

• Amazon SES direct als provider wilt gebruiken,
• een transportaccount van het type ses wilt behouden,
• berichten wilt routeren via Kowal_EmailTransport.

6.1. Een IAM-gebruiker voor verzending aanmaken

Gebruik geen root-account.

Maak een afzonderlijke IAM-gebruiker aan, bijvoorbeeld:

• magento-ses-sender

Wijs daarna een policy toe met minimale rechten voor verzending.

Voorbeeld van een minimale policy

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

Indien gewenst kunt u deze uitbreiden met het uitlezen van limieten of statistieken, maar voor verzending zelf is bovenstaande scope het uitgangspunt.

6.2. Access Key en Secret Key aanmaken

1. Open IAM.
2. Ga naar Users.
3. Open de voorbereide gebruiker.
4. Ga naar het tabblad Security credentials.
5. Kies in de sectie Access keys voor Create access key.
6. Sla het volgende op:
   • Access Key ID
   • Secret Access Key

U ziet het geheim slechts één keer. Als u het verliest, moet u een nieuwe sleutel aanmaken.

6.3. Gegevens die Magento nodig heeft voor de API-variant

Bereid voor het transportaccount ses in Magento het volgende voor:

• provider_region, bijvoorbeeld eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email optioneel,
• store_id als het account alleen voor een specifieke store view moet werken.

6.4. Mapping naar het Magento-paneel

In Kowal / Email Marketing:

1. Voeg een nieuw transportaccount toe.
2. Stel in:
   • Transport Type = Amazon SES,
   • Region = SES-regio,
   • Access Key = IAM-sleutel,
   • Secret Key = IAM-geheim.
3. Sla het account op.
4. Koppel het account aan de berichtrouting.
5. Voer een testverzending uit vanuit het transportaccount.

7. Variant B - integratie via Amazon SES SMTP

Deze variant gebruikt Kowal_EmailSmtp.

Wanneer kiest u voor deze variant

Kies SES SMTP als u:

• Amazon SES als SMTP-bron wilt implementeren,
• het pakket Advance Email Delivery gebruikt,
• aan de Magento-zijde een eenvoudiger integratiemodel wilt behouden.

7.1. SMTP-inloggegevens in SES aanmaken

1. Open Amazon SES.
2. Ga naar SMTP settings.
3. Kies Create SMTP credentials.
4. AWS begeleidt u bij het aanmaken van een IAM-gebruiker voor SMTP.
5. Sla het volgende op:
   • SMTP username
   • SMTP password

Dit zijn geen standaard AWS-sleutels. Dit zijn afzonderlijke SMTP-inloggegevens voor SES.

7.2. SMTP-endpoint

Gebruik voor SES een host in de volgende indeling:

email-smtp..amazonaws.com

Voorbeeld:

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

7.3. Poort en versleuteling

Meest gebruikte instellingen:

• poort 587 + STARTTLS,
• of poort 465 + TLS Wrapper / SSL.

In de praktijk is voor Magento het veiligste startpunt:

• host: email-smtp..amazonaws.com
• poort: 587
• security: STARTTLS

7.4. Gegevens die Magento nodig heeft voor de SMTP-variant

Bereid het volgende voor:

• SMTP-host,
• poort,
• type versleuteling,
• SMTP-login,
• SMTP-wachtwoord,
• afzenderadres dat overeenkomt met de verified identity in SES.

7.5. Mapping naar het Magento-paneel

In Kowal / Email Marketing:

1. Stel in de sectie smtp globaal het volgende in:
   • enabled = Yes,
   • host = SES-endpoint,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = testadres.
2. Sla de configuratie op.
3. Voer Send Test Email uit.

Als u meerdere accounts of meerdere store views gebruikt, kunt u ook een afzonderlijk transportaccount van het type smtp configureren met specifieke verbindingsgegevens.

8. Wat kiezen in dit project

Kies SES API als u:

• transportaccounts van het type ses wilt gebruiken,
• verzending per account en provider wilt routeren,
• transport verder wilt ontwikkelen zonder alles op de SMTP-laag te baseren.

Kies SES SMTP als u:

• sneller een eerste implementatie wilt realiseren,
• SES als externe SMTP-server wilt behandelen,
• vooral een deliverypakket implementeert dat is gebaseerd op Kowal_EmailSmtp.

9. Minimale checklist vóór de verzendtest

Bevestig vóór de eerste test het volgende:

1. Het AWS-account bestaat en facturering is actief.
2. De SES-regio is geselecteerd.
3. Het domein of afzenderadres heeft de status Verified.
4. Het SES-account heeft production access of u test alleen onder sandbox-voorwaarden.
5. DKIM is geconfigureerd.
6. Magento heeft correcte afzendergegevens.
7. De integratievariant is gekozen:
   • API,
   • of SMTP.
8. Inloggegevens zijn veilig opgeslagen.
9. Er is een test verzonden en de aflevering van het bericht is bevestigd.

10. Meest voorkomende fouten

Het account staat nog steeds in sandbox-modus

Symptoom:

• het bericht wordt niet naar normale ontvangers verzonden.

Oorzaak:

• geen production access.

Het domein is niet geverifieerd

Symptoom:

• afzenderfout of afwijzing van verzending.

Oorzaak:

• geen verified identity voor het domein of afzenderadres.

Verkeerde regio

Symptoom:

• de gegevens lijken correct, maar verzending werkt nog steeds niet.

Oorzaak:

• de identiteit is geverifieerd in een andere regio dan die door de integratie wordt gebruikt.

API-sleutels verwarren met SMTP-inloggegevens

Symptoom:

• SMTP-login werkt niet.

Oorzaak:

• er zijn IAM-sleutels ingevuld bij SMTP in plaats van SMTP username en SMTP password.

Gebruik van het root-account

Symptoom:

• geen scheiding van beveiliging en moeilijkere rotatie van inloggegevens.

Oorzaak:

• integratie is gebaseerd op root-gegevens in plaats van een aparte IAM-gebruiker of afzonderlijke SMTP-inloggegevens.

11. Links naar de officiële AWS-documentatie

• 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. Gegevens die voor implementatie moeten worden aangeleverd

Tot slot moet de persoon die SES inricht voor de implementatie precies deze set doorgeven:

Voor de SES API-variant

• SES-regio,
• verified domain,
• access key,
• secret key,
• afzenderadres,
• reply-to, indien dit anders moet zijn,
• informatie of het account globaal of per store view moet werken.

Voor de SES SMTP-variant

• SES-regio,
• SMTP-host,
• poort,
• security mode,
• SMTP username,
• SMTP password,
• afzenderadres,
• testadres voor verificatie.