Advanced Newsletter Suite dla Magento 2 - instrukcja instalacji i konfiguracji

Cel dokumentu

Ten dokument opisuje instalację i konfigurację pakietu magento-2-package-advanced-newsletter-suite. Jest to pełny pakiet newsletterowy i email marketingowy dla Magento 2, obejmujący odbiorców, capture, kampanie, treść, wysyłkę, tracking, panel operacyjny oraz frontendowe punkty zapisu.

Wymagania wstępne

Przed wdrożeniem przygotuj:

• Magento Open Source 2.4.x,
• Composer,
• dostęp CLI do bin/magento,
• konto administratora Magento,
• dane dostępowe do SMTP,
• skonfigurowany cron Magento,
• gotowość do uruchamiania konsumentów kolejek,
• środowisko testowe do sprawdzenia zapisu, kampanii i wysyłek.

Co instaluje pakiet

Pakiet obejmuje:

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

To najwyższy poziom agregacji w ekosystemie modułów email marketingowych dla Magento.

Instalacja

1. Instalacja pakietu Composer

composer config repositories.kowal composer https://repo.kowal.store

composer config http-basic.repo.kowal.store <YOUR E-MAIL> <YOUR-TOKEN>
composer require kowal/package-advanced-newsletter-suite

2. Aktywacja modułów w Magento

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

W trybie produkcyjnym wykonaj dodatkowo:

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

Konfiguracja

1. Sekcja administracyjna

Podstawowa konfiguracja powinna być dostępna w:

Kowal / Email Marketing

Zgodnie ze specyfikacją oczekiwane grupy ustawień to:

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

2. Konfiguracja wysyłki

Najpierw skonfiguruj fundament delivery:

• aktywność modułu,
• domyślny typ transportu,
• logowanie wysyłek,
• konto lub konta SMTP,
• routing wiadomości,
• fallback dla kont zapasowych, jeśli jest używany.

Wdrożenie pełnego pakietu nadal wymaga sprawnej warstwy SMTP i transportu.

3. Konfiguracja odbiorców i zapisów

Następnie potwierdź konfigurację warstwy odbiorców:

• integrację z newsletter_subscriber,
• listy mailingowe,
• segmenty,
• statusy subskrypcji,
• dodatkowe metadane subskrybenta,
• źródła pozyskania,
• zgody marketingowe.

Skonfiguruj również proces zapisu:

• formularze i punkty zapisu,
• double opt-in,
• szablon wiadomości potwierdzającej,
• czas ważności tokenu potwierdzającego.

4. Konfiguracja kampanii

W sekcji campaigns ustaw:

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

Pakiet wspiera:

• definicję kampanii,
• harmonogram,
• kolejkę odbiorców,
• batchowanie wysyłki,
• historię wykonania kampanii,
• wysyłki testowe.

5. Konfiguracja Template Studio

Jeżeli wdrożenie obejmuje pracę z treścią newslettera, skonfiguruj EmailTemplateStudio zgodnie z zakresem MVP:

• pracę na natywnych szablonach newslettera Magento,
• wybór layoutów produktowych,
• zapis wygenerowanej sekcji do natywnego szablonu,
• import gotowej treści do kampanii.

6. Konfiguracja zdarzeń email

W sekcji events skonfiguruj:

• przetwarzanie zdarzeń,
• retencję payloadów,
• politykę akceptowania duplikatów eventów od dostawców.

Warstwa EmailEvents odpowiada za obserwowalność procesu dostarczenia i powiązanie eventów z logami transportu oraz kampaniami.

7. Konfiguracja panelu administracyjnego i frontendu

Pakiet pełny obejmuje:

• Kowal_NewsletterConsole jako panel operacyjny,
• Kowal_NewsletterFrontend jako warstwę frontendowych formularzy i widgetów zapisu.

Po instalacji zweryfikuj:

• dostępność dashboardu,
• skróty do konfiguracji i modułów operacyjnych,
• widok ostatnich błędów i wysyłek,
• obecność formularzy zapisu na frontendzie sklepu.

Cron i konsumenci kolejek

Pełny pakiet wymaga działania przetwarzania asynchronicznego.

1. Cron Magento

bin/magento cron:install

Cron powinien odpowiadać za:

• planowanie kampanii,
• odzyskiwanie zadań,
• watchdog operacyjny.

2. Queue consumers

Konsumenci kolejek powinni odpowiadać za faktyczne przetwarzanie batchy wysyłkowych. Nazwy konsumentów należy pobrać z aktualnych plików etc/queue_consumer.xml wdrożonych modułów.

Na środowisku produkcyjnym zadbaj o:

• uruchamianie consumers w tle,
• autostart po restarcie serwera,
• monitoring awarii,
• logowanie błędów.

Kroki po instalacji

Po wdrożeniu wykonaj pełną listę kontrolną:

1. Skonfiguruj i przetestuj konto SMTP.
2. Zweryfikuj routing wiadomości.
3. Sprawdź zapis subskrybenta i double opt-in.
4. Potwierdź zgodność z natywnym newsletterem Magento.
5. Utwórz listę lub segment testowy.
6. Przygotuj kampanię testową.
7. Wykonaj test send.
8. Sprawdź planowanie kampanii przez cron.
9. Zweryfikuj przetwarzanie kolejki przez consumers.
10. Potwierdź zapis logów i zdarzeń email.
11. Sprawdź dashboard administracyjny.
12. Zweryfikuj frontendowe formularze i widgety zapisu.

Test akceptacyjny po wdrożeniu

Pakiet jest poprawnie wdrożony, jeżeli:

• moduły instalują się poprawnie w Magento 2.4.x,
• wysyłka SMTP działa z poziomu kont i routingu,
• zapis subskrybenta pozostaje zgodny z natywnym newsletterem Magento,
• kampania jest planowana przez cron i przetwarzana przez queue consumer,
• statusy dostarczenia aktualizują logi i zdarzenia email,
• panel administracyjny pokazuje podstawowe dane operacyjne,
• frontendowe punkty zapisu działają poprawnie,
• po wyłączeniu modułów bazowy mechanizm Magento_Newsletter nadal może działać.

Uwagi wdrożeniowe

• Pełny pakiet warto wdrażać razem ze sprawdzoną konfiguracją SMTP i trackingu.
• Dane rozszerzające należy przechowywać we własnych tabelach, bez duplikowania natywnej tabeli newsletter_subscriber.
• Dokumentacja operacyjna wdrożenia powinna dodatkowo obejmować procedurę obsługi kolejek, webhooków i testów regresji konfiguracji administracyjnej.

Amazon SES - założenie konta i konfiguracja do integracji wysyłki

Cel dokumentu

Ten dokument opisuje, jak przygotować konto AWS i usługę Amazon SES tak, aby można było wykonać integrację wysyłki z modułami tego projektu.

Instrukcja obejmuje:

• założenie konta AWS,
• uruchomienie Amazon SES,
• weryfikację domeny i nadawcy,
• wyjście z sandboxa,
• przygotowanie poświadczeń,
• dwa warianty integracji z Magento:
  • przez Amazon SES API,
  • przez Amazon SES SMTP.

Ważna uwaga dla tego projektu

W kodzie projektu są dostępne dwie ścieżki integracji z Amazon SES:

1. SES API w Kowal_EmailTransport z typem transportu ses.
2. SES SMTP w Kowal_EmailSmtp z typem transportu smtp.

To oznacza, że konto AWS i SES warto przygotować raz, ale końcowy sposób podpięcia do Magento zależy od wybranego wariantu wdrożenia.

Założenia wstępne

Przed rozpoczęciem przygotuj:

• domenę, z której będą wysyłane wiadomości, np. example.com,
• dostęp do DNS tej domeny,
• adres nadawcy, np. newsletter@example.com,
• kartę płatniczą lub aktywną metodę rozliczeń w AWS,
• decyzję, w jakim regionie będzie działał SES, np. eu-central-1 albo us-east-1.

1. Założenie konta AWS

1. Wejdź do panelu AWS: https://aws.amazon.com/
2. Załóż konto AWS.
3. Włącz MFA dla konta root.
4. Nie używaj kluczy dostępowych konta root do integracji aplikacji.

Do integracji Magento przygotuj osobnego użytkownika IAM albo osobne poświadczenia SMTP, zależnie od wybranego wariantu.

2. Uruchomienie Amazon SES

1. Zaloguj się do AWS Console.
2. Otwórz usługę Amazon Simple Email Service.
3. Wybierz region, w którym chcesz prowadzić wysyłkę.

To jest ważne, bo w SES region ma znaczenie operacyjne:

• tożsamości nadawcy są utrzymywane per region,
• status sandbox/production access dotyczy regionu,
• dane konfiguracyjne Magento muszą wskazywać ten sam region,
• poświadczenia SMTP w SES są unikalne per region.

Jeżeli sklep działa międzynarodowo, najlepiej od razu ustalić docelowy region dla danego rynku lub całej organizacji i trzymać się go konsekwentnie.

3. Weryfikacja domeny lub adresu nadawcy

Najlepsza praktyka dla sklepu to weryfikacja całej domeny, a nie tylko pojedynczego adresu email.

Rekomendowany wariant

Zweryfikuj domenę, np. example.com.

Dzięki temu:

• możesz wysyłać z wielu adresów tej domeny,
• łatwiej przejść do produkcyjnej wysyłki,
• lepiej przygotowujesz się pod kampanie, transakcje i wiele nadawców,
• łatwiej obsłużyć kilka sklepów, języków i marek w jednym ekosystemie.

Kroki

1. W SES przejdź do Identities.
2. Wybierz Create identity.
3. Wybierz typ Domain.
4. Wpisz domenę wysyłkową.
5. Włącz Easy DKIM, jeśli nie masz powodu używać własnych kluczy DKIM.
6. Dodaj rekordy DNS wskazane przez AWS do swojej strefy DNS.
7. Poczekaj na status Verified.

Minimalny zakres DNS

W praktyce będziesz potrzebować przynajmniej:

• rekordów weryfikacyjnych SES,
• rekordów DKIM,
• opcjonalnie rekordu dla custom MAIL FROM.

4. Wyjście z sandboxa SES

Nowe konto SES zwykle działa początkowo w sandboxie.

To oznacza między innymi, że:

• możesz wysyłać tylko z zweryfikowanych tożsamości,
• odbiorcy również muszą być zweryfikowani,
• nie wykonasz normalnej produkcyjnej wysyłki do klientów sklepu.

Kroki

1. W SES otwórz Account dashboard albo ekran startowy konfiguracji.
2. Wybierz opcję Request production access.
3. Uzupełnij formularz zgodnie z przeznaczeniem systemu:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Opisz, że wysyłka będzie realizowana z własnego Magento dla sklepu internetowego.
5. Wyślij wniosek.

Przed wysłaniem wniosku dobrze jest mieć już zweryfikowaną domenę. To zwykle przyspiesza akceptację.

5. Konfiguracja dostarczalności

To nie jest obowiązkowe minimum do pierwszego testu, ale jest mocno zalecane przed produkcją.

DKIM

Jeżeli używasz Easy DKIM, SES podpisuje wiadomości automatycznie po poprawnej konfiguracji DNS.

Custom MAIL FROM

Jeżeli chcesz poprawić kontrolę nad nadawcą technicznym i dostarczalnością:

1. Otwórz zweryfikowaną domenę w SES.
2. Skonfiguruj Custom MAIL FROM domain, np. mail.example.com.
3. Dodaj do DNS:
   • rekord MX,
   • rekord SPF/TXT dla MAIL FROM.

To jest szczególnie sensowne dla sklepów, które prowadzą regularny email marketing i chcą ograniczyć problemy z reputacją nadawcy.

6. Wariant A - integracja przez Amazon SES API

Ten wariant wykorzystuje typ transportu ses dostępny w Kowal_EmailTransport.

Kiedy wybrać ten wariant

Wybierz SES API, jeżeli:

• chcesz korzystać bezpośrednio z Amazon SES jako providera,
• chcesz utrzymywać konto transportowe typu ses,
• chcesz routingować wiadomości przez Kowal_EmailTransport.

6.1. Utworzenie użytkownika IAM do wysyłki

Nie używaj konta root.

Przygotuj osobnego użytkownika IAM, np.:

• magento-ses-sender

Następnie przypisz mu politykę z minimalnymi uprawnieniami do wysyłki.

Przykładowa polityka minimalna

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

Jeżeli chcesz, możesz rozszerzyć ją o odczyt limitów lub statystyk, ale do samej wysyłki powyższy zakres jest punktem wyjścia.

6.2. Utworzenie Access Key i Secret Key

1. Otwórz IAM.
2. Przejdź do Users.
3. Otwórz przygotowanego użytkownika.
4. Wejdź w zakładkę Security credentials.
5. W sekcji Access keys wybierz Create access key.
6. Zapisz:
   • Access Key ID
   • Secret Access Key

Sekret zobaczysz tylko raz. Jeżeli go zgubisz, musisz utworzyć nowy klucz.

6.3. Dane potrzebne do Magento dla wariantu API

Do konta transportowego ses w Magento przygotuj:

• provider_region, np. eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email opcjonalnie,
• store_id, jeżeli konto ma działać tylko dla konkretnego store view.

6.4. Mapowanie do panelu Magento

W Kowal / Email Marketing:

1. Dodaj nowe konto transportowe.
2. Ustaw:
   • Transport Type = Amazon SES,
   • Region = region SES,
   • Access Key = klucz IAM,
   • Secret Key = sekret IAM.
3. Zapisz konto.
4. Powiąż konto z routingiem wiadomości.
5. Wykonaj test wysyłki z poziomu konta transportowego.

7. Wariant B - integracja przez Amazon SES SMTP

Ten wariant wykorzystuje Kowal_EmailSmtp.

Kiedy wybrać ten wariant

Wybierz SES SMTP, jeżeli:

• chcesz wdrożyć Amazon SES jako źródło SMTP,
• korzystasz z pakietu Advance Email Delivery,
• chcesz zachować prostszy model integracji po stronie Magento.

7.1. Utworzenie poświadczeń SMTP w SES

1. Otwórz Amazon SES.
2. Przejdź do SMTP settings.
3. Wybierz Create SMTP credentials.
4. AWS przeprowadzi Cię przez utworzenie użytkownika IAM dla SMTP.
5. Zapisz:
   • SMTP username
   • SMTP password

To nie są zwykłe klucze AWS. To osobne poświadczenia SMTP dla SES.

7.2. Endpoint SMTP

Dla SES użyj hosta w formacie:

email-smtp.<region>.amazonaws.com

Przykład:

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

7.3. Port i szyfrowanie

Najczęściej używane ustawienia:

• port 587 + STARTTLS,
• albo port 465 + TLS Wrapper / SSL.

W praktyce dla Magento najbezpieczniejszy punkt startowy to:

• host: email-smtp.<region>.amazonaws.com
• port: 587
• security: STARTTLS

7.4. Dane potrzebne do Magento dla wariantu SMTP

Przygotuj:

• host SMTP,
• port,
• typ szyfrowania,
• login SMTP,
• hasło SMTP,
• adres nadawcy zgodny z verified identity w SES.

7.5. Mapowanie do panelu Magento

W Kowal / Email Marketing:

1. W sekcji smtp ustaw globalnie:
   • enabled = Yes,
   • host = endpoint SES,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = adres do testu.
2. Zapisz konfigurację.
3. Wykonaj Send Test Email.

Jeżeli używasz wielu kont lub wielu store view, możesz też skonfigurować osobne konto transportowe typu smtp z dedykowanymi danymi połączenia.

8. Co wybrać w tym projekcie

Wybierz SES API, jeżeli:

• chcesz używać kont transportowych ses,
• chcesz routingować wysyłkę per konto i provider,
• chcesz rozwijać transport bez opierania wszystkiego na warstwie SMTP.

Wybierz SES SMTP, jeżeli:

• zależy Ci na szybszym pierwszym wdrożeniu,
• chcesz traktować SES jak zewnętrzny serwer SMTP,
• wdrażasz głównie pakiet delivery oparty o Kowal_EmailSmtp.

9. Minimalna checklista przed testem wysyłki

Przed pierwszym testem potwierdź:

1. Konto AWS istnieje i ma aktywne rozliczenia.
2. Region SES został wybrany.
3. Domena albo adres nadawcy mają status Verified.
4. Konto SES ma production access albo testujesz tylko w warunkach sandboxa.
5. DKIM jest skonfigurowany.
6. Magento ma poprawne dane nadawcy.
7. Wariant integracji został wybrany:
   • API,
   • albo SMTP.
8. Poświadczenia są zapisane bezpiecznie.
9. Wysłano test i potwierdzono dostarczenie wiadomości.

10. Najczęstsze błędy

Konto nadal jest w sandboxie

Objaw:

• wiadomość nie wychodzi do normalnych odbiorców.

Przyczyna:

• brak production access.

Domena nie jest zweryfikowana

Objaw:

• błąd nadawcy albo odrzucenie wysyłki.

Przyczyna:

• brak verified identity dla domeny lub adresu nadawcy.

Zły region

Objaw:

• dane wyglądają poprawnie, ale wysyłka nadal nie działa.

Przyczyna:

• tożsamość jest zweryfikowana w innym regionie niż ten użyty przez integrację.

Pomylenie kluczy API z poświadczeniami SMTP

Objaw:

• logowanie SMTP nie działa.

Przyczyna:

• do SMTP wpisano klucze IAM zamiast SMTP username i SMTP password.

Użycie konta root

Objaw:

• brak separacji bezpieczeństwa i trudniejsza rotacja poświadczeń.

Przyczyna:

• integracja oparta o dane root zamiast osobnego użytkownika IAM albo osobnych poświadczeń SMTP.

11. Linki do oficjalnej dokumentacji AWS

• 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. Dane, które trzeba przekazać do wdrożenia

Na końcu osoba zakładająca SES powinna przekazać do wdrożenia dokładnie ten zestaw:

Dla wariantu SES API

• region SES,
• verified domain,
• access key,
• secret key,
• adres nadawcy,
• reply-to, jeśli ma być inny,
• informację, czy konto ma działać globalnie czy per store view.

Dla wariantu SES SMTP

• region SES,
• host SMTP,
• port,
• security mode,
• SMTP username,
• SMTP password,
• adres nadawcy,
• adres testowy do weryfikacji.