Amazon SES - creazione dell'account e configurazione per l'integrazione dell'invio

Scopo del documento

Questo documento descrive come preparare un account AWS e il servizio Amazon SES affinché sia possibile eseguire l'integrazione dell'invio con i moduli di questo progetto.

Le istruzioni comprendono:

• creazione di un account AWS,
• attivazione di Amazon SES,
• verifica del dominio e del mittente,
• uscita dalla sandbox,
• preparazione delle credenziali,
• due varianti di integrazione con Magento:
  • tramite Amazon SES API,
  • tramite Amazon SES SMTP.

Nota importante per questo progetto

Nel codice del progetto sono disponibili due percorsi di integrazione con Amazon SES:

1. SES API in Kowal_EmailTransport con tipo di trasporto ses.
2. SES SMTP in Kowal_EmailSmtp con tipo di trasporto smtp.

Ciò significa che l'account AWS e SES conviene prepararli una sola volta, ma la modalità finale di collegamento a Magento dipende dalla variante di implementazione scelta.

Prerequisiti

Prima di iniziare prepara:

• il dominio da cui verranno inviati i messaggi, ad esempio example.com,
• accesso al DNS di quel dominio,
• indirizzo del mittente, ad esempio newsletter@example.com,
• carta di pagamento o metodo di fatturazione attivo in AWS,
• decisione sulla regione in cui opererà SES, ad esempio eu-central-1 oppure us-east-1.

1. Creazione dell'account AWS

1. Accedi al pannello AWS: https://aws.amazon.com/
2. Crea un account AWS.
3. Abilita MFA per l'account root.
4. Non utilizzare le chiavi di accesso dell'account root per l'integrazione dell'applicazione.

Per l'integrazione con Magento prepara un utente IAM separato oppure credenziali SMTP separate, a seconda della variante scelta.

2. Attivazione di Amazon SES

1. Accedi alla AWS Console.
2. Apri il servizio Amazon Simple Email Service.
3. Seleziona la regione in cui desideri gestire l'invio.

Questo è importante, perché in SES la regione ha un ruolo operativo:

• le identità del mittente sono mantenute per regione,
• lo stato sandbox/production access riguarda la regione,
• i dati di configurazione di Magento devono indicare la stessa regione,
• le credenziali SMTP in SES sono uniche per regione.

Se il negozio opera a livello internazionale, è meglio definire subito la regione di destinazione per il mercato o per l'intera organizzazione e mantenerla in modo coerente.

3. Verifica del dominio o dell'indirizzo mittente

La best practice per un negozio è verificare l'intero dominio, non solo un singolo indirizzo email.

Variante consigliata

Verifica il dominio, ad esempio example.com.

In questo modo:

• puoi inviare da più indirizzi di quel dominio,
• è più facile passare all'invio in produzione,
• ti prepari meglio per campagne, messaggi transazionali e più mittenti,
• è più facile gestire più negozi, lingue e brand in un unico ecosistema.

Passaggi

1. In SES vai su Identities.
2. Seleziona Create identity.
3. Scegli il tipo Domain.
4. Inserisci il dominio di invio.
5. Abilita Easy DKIM, se non hai motivo di usare chiavi DKIM personalizzate.
6. Aggiungi i record DNS indicati da AWS alla tua zona DNS.
7. Attendi lo stato Verified.

Ambito minimo DNS

In pratica avrai bisogno almeno di:

• record di verifica SES,
• record DKIM,
• facoltativamente un record per custom MAIL FROM.

4. Uscita dalla sandbox SES

Un nuovo account SES di solito inizialmente opera in sandbox.

Questo significa, tra l'altro, che:

• puoi inviare solo da identità verificate,
• anche i destinatari devono essere verificati,
• non potrai effettuare un normale invio in produzione ai clienti del negozio.

Passaggi

1. In SES apri Account dashboard oppure la schermata iniziale di configurazione.
2. Seleziona l'opzione Request production access.
3. Compila il modulo in base alla destinazione del sistema:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Descrivi che l'invio sarà effettuato dal tuo Magento per un negozio online.
5. Invia la richiesta.

Prima di inviare la richiesta è consigliabile avere già il dominio verificato. Questo di solito accelera l'approvazione.

5. Configurazione della deliverability

Non è il minimo obbligatorio per il primo test, ma è fortemente consigliato prima della produzione.

DKIM

Se utilizzi Easy DKIM, SES firma i messaggi automaticamente dopo la corretta configurazione DNS.

Custom MAIL FROM

Se vuoi migliorare il controllo sul mittente tecnico e sulla deliverability:

1. Apri il dominio verificato in SES.
2. Configura Custom MAIL FROM domain, ad esempio mail.example.com.
3. Aggiungi al DNS:
   • record MX,
   • record SPF/TXT per MAIL FROM.

Questo è particolarmente sensato per i negozi che gestiscono email marketing regolare e vogliono limitare i problemi di reputazione del mittente.

6. Variante A - integrazione tramite Amazon SES API

Questa variante utilizza il tipo di trasporto ses disponibile in Kowal_EmailTransport.

Quando scegliere questa variante

Scegli SES API se:

• vuoi usare Amazon SES direttamente come provider,
• vuoi mantenere un account di trasporto di tipo ses,
• vuoi instradare i messaggi tramite Kowal_EmailTransport.

6.1. Creazione dell'utente IAM per l'invio

Non utilizzare l'account root.

Prepara un utente IAM separato, ad esempio:

• magento-ses-sender

Successivamente assegnagli una policy con permessi minimi per l'invio.

Esempio di policy minima

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

Se vuoi, puoi estenderla con la lettura dei limiti o delle statistiche, ma per il solo invio questo ambito è il punto di partenza.

6.2. Creazione di Access Key e Secret Key

1. Apri IAM.
2. Vai su Users.
3. Apri l'utente preparato.
4. Entra nella scheda Security credentials.
5. Nella sezione Access keys seleziona Create access key.
6. Salva:
   • Access Key ID
   • Secret Access Key

Il segreto sarà visibile una sola volta. Se lo perdi, dovrai creare una nuova chiave.

6.3. Dati necessari per Magento per la variante API

Per l'account di trasporto ses in Magento prepara:

• provider_region, ad esempio eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email facoltativo,
• store_id, se l'account deve funzionare solo per una specifica store view.

6.4. Mappatura nel pannello Magento

In Kowal / Email Marketing:

1. Aggiungi un nuovo account di trasporto.
2. Imposta:
   • Transport Type = Amazon SES,
   • Region = regione SES,
   • Access Key = chiave IAM,
   • Secret Key = segreto IAM.
3. Salva l'account.
4. Collega l'account al routing dei messaggi.
5. Esegui un test di invio dall'account di trasporto.

7. Variante B - integrazione tramite Amazon SES SMTP

Questa variante utilizza Kowal_EmailSmtp.

Quando scegliere questa variante

Scegli SES SMTP se:

• vuoi implementare Amazon SES come sorgente SMTP,
• utilizzi il pacchetto Advance Email Delivery,
• vuoi mantenere un modello di integrazione più semplice dal lato Magento.

7.1. Creazione delle credenziali SMTP in SES

1. Apri Amazon SES.
2. Vai su SMTP settings.
3. Seleziona Create SMTP credentials.
4. AWS ti guiderà nella creazione di un utente IAM per SMTP.
5. Salva:
   • SMTP username
   • SMTP password

Queste non sono normali chiavi AWS. Sono credenziali SMTP separate per SES.

7.2. Endpoint SMTP

Per SES usa un host nel formato:

email-smtp..amazonaws.com

Esempio:

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

7.3. Porta e crittografia

Impostazioni più comunemente usate:

• porta 587 + STARTTLS,
• oppure porta 465 + TLS Wrapper / SSL.

In pratica, per Magento il punto di partenza più sicuro è:

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

7.4. Dati necessari per Magento per la variante SMTP

Prepara:

• host SMTP,
• porta,
• tipo di crittografia,
• login SMTP,
• password SMTP,
• indirizzo mittente conforme alla verified identity in SES.

7.5. Mappatura nel pannello Magento

In Kowal / Email Marketing:

1. Nella sezione smtp imposta globalmente:
   • enabled = Yes,
   • host = endpoint SES,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = indirizzo per il test.
2. Salva la configurazione.
3. Esegui Send Test Email.

Se utilizzi più account o più store view, puoi anche configurare un account di trasporto separato di tipo smtp con dati di connessione dedicati.

8. Cosa scegliere in questo progetto

Scegli SES API se:

• vuoi usare account di trasporto ses,
• vuoi instradare l'invio per account e provider,
• vuoi sviluppare il trasporto senza basarti interamente sul livello SMTP.

Scegli SES SMTP se:

• ti interessa una prima implementazione più rapida,
• vuoi trattare SES come un server SMTP esterno,
• stai implementando principalmente il pacchetto delivery basato su Kowal_EmailSmtp.

9. Checklist minima prima del test di invio

Prima del primo test conferma che:

1. L'account AWS esiste e ha la fatturazione attiva.
2. La regione SES è stata selezionata.
3. Il dominio o l'indirizzo del mittente hanno stato Verified.
4. L'account SES ha production access oppure stai testando solo in condizioni sandbox.
5. DKIM è configurato.
6. Magento ha dati mittente corretti.
7. La variante di integrazione è stata scelta:
   • API,
   • oppure SMTP.
8. Le credenziali sono salvate in modo sicuro.
9. Il test è stato inviato e la consegna del messaggio è stata confermata.

10. Errori più frequenti

L'account è ancora in sandbox

Sintomo:

• il messaggio non viene inviato a destinatari normali.

Causa:

• mancanza di production access.

Il dominio non è verificato

Sintomo:

• errore del mittente o rifiuto dell'invio.

Causa:

• mancanza di verified identity per il dominio o per l'indirizzo del mittente.

Regione errata

Sintomo:

• i dati sembrano corretti, ma l'invio continua a non funzionare.

Causa:

• l'identità è verificata in una regione diversa da quella usata dall'integrazione.

Confusione tra chiavi API e credenziali SMTP

Sintomo:

• l'accesso SMTP non funziona.

Causa:

• in SMTP sono state inserite chiavi IAM invece di SMTP username e SMTP password.

Uso dell'account root

Sintomo:

• mancanza di separazione della sicurezza e rotazione più difficile delle credenziali.

Causa:

• integrazione basata su dati root invece che su un utente IAM separato o credenziali SMTP separate.

11. Link alla documentazione ufficiale 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. Dati da fornire per l'implementazione

Alla fine, la persona che configura SES dovrebbe fornire per l'implementazione esattamente questo set:

Per la variante SES API

• regione SES,
• verified domain,
• access key,
• secret key,
• indirizzo mittente,
• reply-to, se deve essere diverso,
• informazione se l'account deve funzionare globalmente o per store view.

Per la variante SES SMTP

• regione SES,
• host SMTP,
• porta,
• security mode,
• SMTP username,
• SMTP password,
• indirizzo mittente,
• indirizzo di test per la verifica.

Advanced Newsletter Suite per Magento 2 - istruzioni di installazione e configurazione

Scopo del documento

Questo documento descrive l'installazione e la configurazione del pacchettomagento-2-package-advanced-newsletter-suite. È una suite completa per newsletter ed email marketing per Magento 2, che include destinatari, capture, campagne, contenuti, invio, tracking, pannello operativo e punti di iscrizione sul frontend.

Prerequisiti

Prima dell'implementazione, prepara:

• Magento Open Source2.4.x,
• Composer,
• accesso CLI abin/magento,
• account amministratore Magento,
• dati di accesso SMTP,
• cron Magento configurato,
• disponibilità ad avviare i consumer delle code,
• ambiente di test per verificare iscrizione, campagne e invii.

Cosa installa il pacchetto

Il pacchetto include:

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

È il massimo livello di aggregazione nell'ecosistema dei moduli di email marketing per Magento.

Installazione

1. Installazione del pacchetto Composer

I dati di accesso al repository Composer, ovvero l indirizzo e-mail del cliente e il token di licenza, saranno inviati via e-mail dopo l acquisto. Sono disponibili anche nel pannello cliente dopo l accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

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

composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"
composer require kowal/package-advanced-newsletter-suite

2. Attivazione dei moduli 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_NewsletterFrontend
bin/magento setup:upgrade
bin/magento cache:flush

In modalità produzione, esegui inoltre:

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

Configurazione

1. Sezione amministrativa

La configurazione di base dovrebbe essere disponibile in:

Kowal / Email Marketing

Secondo la specifica, i gruppi di impostazioni previsti sono:

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

2. Configurazione dell'invio

Per prima cosa configura la base del delivery:

• attività del modulo,
• tipo di trasporto predefinito,
• logging degli invii,
• account o account SMTP,
• routing dei messaggi,
• fallback per gli account di riserva, se utilizzato.

L'implementazione della suite completa richiede comunque un livello SMTP e di trasporto funzionante.

3. Configurazione di destinatari e iscrizioni

Successivamente conferma la configurazione del livello destinatari:

• integrazione connewsletter_subscriber,
• liste mailing,
• segmenti,
• stati di sottoscrizione,
• metadati aggiuntivi del sottoscrittore,
• fonti di acquisizione,
• consensi marketing.

Configura anche il processo di iscrizione:

• moduli e punti di iscrizione,
• double opt-in,
• template del messaggio di conferma,
• tempo di validità del token di conferma.

4. Configurazione delle campagne

Nella sezionecampaignsimposta:

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

Il pacchetto supporta:

• definizione della campagna,
• pianificazione,
• coda dei destinatari,
• invio in batch,
• cronologia di esecuzione della campagna,
• invii di test.

5. Configurazione di Template Studio

Se l'implementazione include il lavoro sui contenuti della newsletter, configuraEmailTemplateStudioin conformità con l'ambito MVP:

• lavoro sui template newsletter nativi di Magento,
• selezione dei layout prodotto,
• salvataggio della sezione generata nel template nativo,
• importazione dei contenuti pronti nella campagna.

6. Configurazione degli eventi email

Nella sezioneeventsconfigura:

• elaborazione degli eventi,
• retention dei payload,
• policy di accettazione dei duplicati degli eventi dai provider.

Il livelloEmailEventsè responsabile dell'osservabilità del processo di consegna e del collegamento degli eventi con i log di trasporto e le campagne.

7. Configurazione del pannello amministrativo e del frontend

Il pacchetto completo include:

• Kowal_NewsletterConsolecome pannello operativo,
• Kowal_NewsletterFrontendcome livello per moduli e widget di iscrizione frontend.

Dopo l'installazione verifica:

• disponibilità della dashboard,
• scorciatoie alla configurazione e ai moduli operativi,
• vista degli ultimi errori e invii,
• presenza dei moduli di iscrizione sul frontend del negozio.

Cron e consumer delle code

Il pacchetto completo richiede il funzionamento dell'elaborazione asincrona.

1. Cron Magento

bin/magento cron:install

Cron dovrebbe essere responsabile di:

• pianificazione delle campagne,
• recupero delle attività,
• watchdog operativo.

2. Queue consumers

I consumer delle code dovrebbero essere responsabili dell'elaborazione effettiva dei batch di invio. I nomi dei consumer devono essere recuperati dai file aggiornatietc/queue_consumer.xmldei moduli implementati.

Nell'ambiente di produzione assicurati di:

• eseguire i consumer in background,
• abilitare l'avvio automatico dopo il riavvio del server,
• monitorare i guasti,
• registrare gli errori.

Passaggi dopo l'installazione

Dopo l'implementazione, esegui la checklist completa:

1. Configura e testa l'account SMTP.
2. Verifica il routing dei messaggi.
3. Controlla l'iscrizione del sottoscrittore e il double opt-in.
4. Conferma la compatibilità con la newsletter nativa di Magento.
5. Crea una lista o un segmento di test.
6. Prepara una campagna di test.
7. Esegui un invio di test.
8. Controlla la pianificazione della campagna tramite cron.
9. Verifica l'elaborazione della coda da parte dei consumer.
10. Conferma il salvataggio dei log e degli eventi email.
11. Controlla la dashboard amministrativa.
12. Verifica i moduli e i widget di iscrizione frontend.

Test di accettazione dopo l'implementazione

Il pacchetto è implementato correttamente se:

• i moduli si installano correttamente in Magento 2.4.x,
• l'invio SMTP funziona a livello di account e routing,
• l'iscrizione del sottoscrittore rimane conforme alla newsletter nativa di Magento,
• la campagna viene pianificata tramitecroned elaborata daqueue consumer,
• gli stati di consegna aggiornano i log e gli eventi email,
• il pannello amministrativo mostra i dati operativi di base,
• i punti di iscrizione frontend funzionano correttamente,
• dopo la disattivazione dei moduli, il meccanismo di baseMagento_Newsletterpuò continuare a funzionare.

Note di implementazione

• Conviene implementare il pacchetto completo insieme a una configurazione SMTP e di tracking verificata.
• I dati di estensione devono essere conservati in tabelle dedicate, senza duplicare la tabella nativanewsletter_subscriber.
• La documentazione operativa dell'implementazione dovrebbe includere inoltre la procedura di gestione di code, webhook e test di regressione della configurazione amministrativa.