Advanced Newsletter Suite per Magento 2 - guida all installazione e alla configurazione

Scopo del documento

Questo documento descrive l installazione e la configurazione del pacchetto magento-2-package-advanced-newsletter-suite. È un pacchetto completo per newsletter ed email marketing per Magento 2, che comprende destinatari, capture, campagne, contenuti, invio, tracking, pannello operativo e punti di iscrizione frontend.

Prerequisiti

Prima dell implementazione prepara:

• Magento Open Source 2.4.x,
• Composer,
• accesso CLI a bin/magento,
• account amministratore Magento,
• credenziali 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.

Si tratta del più alto livello di aggregazione nell ecosistema dei moduli di email marketing per Magento.

Installazione

1. Installazione del pacchetto Composer

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. 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_NewsletterFrontendbin/magento setup:upgradebin/magento cache:flush

In modalità produzione esegui inoltre:

bin/magento setup:di:compilebin/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 le basi del delivery:

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

L implementazione del pacchetto completo richiede comunque un livello SMTP e di transport funzionante.

3. Configurazione dei destinatari e delle iscrizioni

Successivamente conferma la configurazione del livello destinatari:

• integrazione con newsletter_subscriber,
• mailing list,
• segmenti,
• stati di iscrizione,
• metadati aggiuntivi dell iscritto,
• 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 sezione campaigns imposta:

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

Il pacchetto supporta:

• definizione delle campagne,
• pianificazione,
• coda dei destinatari,
• batchizzazione degli invii,
• storico di esecuzione delle campagne,
• invii di test.

5. Configurazione di Template Studio

Se l implementazione include il lavoro sui contenuti della newsletter, configura EmailTemplateStudio in base all ambito MVP:

• lavoro sui template newsletter nativi di Magento,
• selezione dei layout prodotto,
• salvataggio della sezione generata nel template nativo,
• import del contenuto pronto nella campagna.

6. Configurazione degli eventi email

Nella sezione events configura:

• elaborazione degli eventi,
• retention dei payload,
• politica di accettazione dei duplicati degli eventi da parte dei provider.

Il livello EmailEvents è responsabile dell osservabilità del processo di consegna e del collegamento degli eventi ai log di trasporto e alle campagne.

7. Configurazione del pannello amministrativo e del frontend

Il pacchetto completo include:

• Kowal_NewsletterConsole come pannello operativo,
• Kowal_NewsletterFrontend come livello di moduli frontend e widget di iscrizione.

Dopo l installazione verifica:

• disponibilità della dashboard,
• collegamenti rapidi alla configurazione e ai moduli operativi,
• vista degli ultimi errori e invii,
• presenza dei moduli di iscrizione sul frontend dello store.

Cron e consumer delle code

Il pacchetto completo richiede l esecuzione dell elaborazione asincrona.

1. Cron Magento

bin/magento cron:install

Il cron dovrebbe essere responsabile di:

• pianificazione delle campagne,
• recupero dei task,
• 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 presi dai file attuali etc/queue_consumer.xml dei moduli implementati.

In ambiente di produzione assicurati di avere:

• esecuzione dei consumer in background,
• avvio automatico dopo il riavvio del server,
• monitoraggio dei guasti,
• log degli errori.

Passaggi dopo l installazione

Dopo l implementazione esegui una checklist completa:

1. Configura e testa l account SMTP.
2. Verifica il routing dei messaggi.
3. Controlla l iscrizione dell utente 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 test send.
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 frontend e i widget di iscrizione.

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 dell utente resta compatibile con la newsletter nativa di Magento,
• la campagna viene pianificata da cron e processata da queue 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 base Magento_Newsletter può ancora funzionare.

Note di implementazione

• Il pacchetto completo conviene implementarlo insieme a una configurazione SMTP e tracking già verificata.
• I dati estesi devono essere archiviati nelle proprie tabelle, senza duplicare la tabella nativa newsletter_subscriber.
• La documentazione operativa dell implementazione dovrebbe inoltre includere la procedura di gestione delle code, dei webhook e dei test di regressione della configurazione amministrativa.

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 in modo da poter eseguire l integrazione dell invio con i moduli di questo progetto.

La guida include:

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

Questo significa che vale la pena preparare una sola volta l account AWS e SES, ma il modo finale di collegamento a Magento dipende dalla variante di implementazione scelta.

Presupposti iniziali

Prima di iniziare prepara:

• il dominio da cui verranno inviate le email, ad esempio example.com,
• accesso al DNS di questo dominio,
• indirizzo del mittente, ad esempio newsletter@example.com,
• carta di pagamento o metodo di fatturazione attivo in AWS,
• decisione su in quale regione verrà eseguito SES, ad esempio eu-central-1 oppure us-east-1.

1. Creazione dell account AWS

1. Vai 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 Magento prepara un utente IAM separato oppure credenziali SMTP separate, a seconda della variante scelta.

2. Attivazione di Amazon SES

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

Questo è importante perché in SES la regione ha rilevanza operativa:

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

Se lo store opera a livello internazionale, è meglio definire subito la regione target 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 uno store è 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 molti indirizzi del dominio,
• è più facile passare all invio in produzione,
• ti prepari meglio per campagne, transazioni e più mittenti,
• è più facile gestire più store, lingue e brand in un unico ecosistema.

Passaggi

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

Ambito DNS minimo

In pratica ti serviranno almeno:

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

4. Uscita dalla sandbox SES

Un nuovo account SES di solito opera inizialmente 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 dello store.

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 uno store online.
5. Invia la richiesta.

Prima di inviare la richiesta è utile 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 del 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 gli store 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 utilizzare direttamente Amazon SES come provider,
• vuoi mantenere un account di trasporto di tipo ses,
• vuoi instradare i messaggi tramite Kowal_EmailTransport.

6.1. Creazione di un utente IAM per l invio

Non utilizzare l account root.

Prepara un utente IAM separato, ad esempio:

• magento-ses-sender

Successivamente assegna una policy con i 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 ampliarla con la lettura di limiti o statistiche, ma per il solo invio l ambito sopra è 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. Vai alla scheda Security credentials.
5. Nella sezione Access keys seleziona Create access key.
6. Salva:
   • Access Key ID
   • Secret Access Key

Vedrai il secret solo una 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 = secret IAM.
3. Salva l account.
4. Associa l account al routing dei messaggi.
5. Esegui un test di invio dal livello dell 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 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 utilizza un host nel formato:

email-smtp..amazonaws.com

Esempio:

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

7.3. Porta e crittografia

Le impostazioni più usate sono:

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

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

• host: email-smtp..amazonaws.com
• port: 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 del 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 gli invii per account e provider,
• vuoi sviluppare il transport senza basare tutto sul livello SMTP.

Scegli SES SMTP se:

• ti interessa una prima implementazione più rapida,
• vuoi trattare SES come 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 mittente hanno stato Verified.
4. L account SES ha production access oppure stai testando solo in condizioni di 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. È stato inviato un test ed è stata confermata la consegna del messaggio.

10. Errori più comuni

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 oppure rifiuto dell invio.

Causa:

• mancanza di verified identity per il dominio o l indirizzo 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 autenticazione SMTP non funziona.

Causa:

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

Utilizzo dell account root

Sintomo:

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

Causa:

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

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 trasmettere per l implementazione

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

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.