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.