Advanced Newsletter Suite pour Magento 2 - guide d'installation et de configuration

Objectif du document

Ce document décrit l'installation et la configuration du pack magento-2-package-advanced-newsletter-suite. Il s'agit d'un pack complet de newsletter et d'email marketing pour Magento 2, couvrant les destinataires, capture, les campagnes, le contenu, l'envoi, le tracking, le panneau opérationnel ainsi que les points d'inscription frontend.

Prérequis

Avant le déploiement, préparez :

• Magento Open Source 2.4.x,
• Composer,
• un accès CLI à bin/magento,
• un compte administrateur Magento,
• les identifiants d'accès SMTP,
• un cron Magento configuré,
• la capacité à lancer les consommateurs de files d'attente,
• un environnement de test pour vérifier l'inscription, les campagnes et les envois.

Ce que le pack installe

Le pack comprend :

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

Il s'agit du plus haut niveau d'agrégation dans l'écosystème des modules d'email marketing pour Magento.

Installation

1. Installation du pack 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. Activation des modules dans 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

En mode production, exécutez également :

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

Configuration

1. Section d'administration

La configuration de base doit être disponible dans :

Kowal / Email Marketing

Conformément à la spécification, les groupes de paramètres attendus sont :

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

2. Configuration de l'envoi

Configurez d'abord la base de la delivery :

• activité du module,
• type de transport par défaut,
• journalisation des envois,
• compte ou comptes SMTP,
• routing des messages,
• fallback pour les comptes de secours, s'il est utilisé.

Le déploiement du pack complet nécessite toujours une couche SMTP et transport pleinement fonctionnelle.

3. Configuration des destinataires et des inscriptions

Ensuite, confirmez la configuration de la couche des destinataires :

• intégration avec newsletter_subscriber,
• listes de diffusion,
• segments,
• statuts d'abonnement,
• métadonnées supplémentaires de l'abonné,
• sources d'acquisition,
• consentements marketing.

Configurez également le processus d'inscription :

• formulaires et points d'inscription,
• double opt-in,
• modèle du message de confirmation,
• durée de validité du token de confirmation.

4. Configuration des campagnes

Dans la section campaigns, définissez :

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

Le pack prend en charge :

• la définition des campagnes,
• le calendrier,
• la file des destinataires,
• le batch processing des envois,
• l'historique d'exécution des campagnes,
• les envois de test.

5. Configuration de Template Studio

Si le déploiement comprend le travail sur le contenu de la newsletter, configurez EmailTemplateStudio conformément au périmètre MVP :

• travail sur les modèles natifs de newsletter de Magento,
• choix des layouts produits,
• enregistrement de la section générée dans le modèle natif,
• import du contenu prêt dans la campagne.

6. Configuration des événements email

Dans la section events, configurez :

• le traitement des événements,
• la rétention des payloads,
• la politique d'acceptation des doublons d'événements provenant des fournisseurs.

La couche EmailEvents est responsable de l'observabilité du processus de livraison et du lien entre les événements, les logs de transport et les campagnes.

7. Configuration du panneau d'administration et du frontend

Le pack complet comprend :

• Kowal_NewsletterConsole comme panneau opérationnel,
• Kowal_NewsletterFrontend comme couche des formulaires frontend et des widgets d'inscription.

Après l'installation, vérifiez :

• la disponibilité du dashboard,
• les raccourcis vers la configuration et les modules opérationnels,
• la vue des dernières erreurs et des derniers envois,
• la présence des formulaires d'inscription sur le frontend de la boutique.

Cron et consommateurs de files d'attente

Le pack complet nécessite un traitement asynchrone opérationnel.

1. Cron Magento

bin/magento cron:install

Le cron doit être responsable de :

• la planification des campagnes,
• la récupération des tâches,
• le watchdog opérationnel.

2. Queue consumers

Les consommateurs de files d'attente doivent être responsables du traitement effectif des batches d'envoi. Les noms des consommateurs doivent être récupérés dans les fichiers actuels etc/queue_consumer.xml des modules déployés.

En environnement de production, veillez à :

• exécuter les consumers en arrière-plan,
• les démarrer automatiquement après un redémarrage du serveur,
• superviser les pannes,
• journaliser les erreurs.

Étapes après l'installation

Après le déploiement, exécutez la checklist complète :

1. Configurez et testez le compte SMTP.
2. Vérifiez le routing des messages.
3. Contrôlez l'inscription d'un abonné et le double opt-in.
4. Confirmez la compatibilité avec la newsletter native de Magento.
5. Créez une liste ou un segment de test.
6. Préparez une campagne de test.
7. Effectuez un test send.
8. Vérifiez la planification des campagnes par cron.
9. Contrôlez le traitement de la file d'attente par les consumers.
10. Confirmez l'enregistrement des logs et des événements email.
11. Vérifiez le dashboard d'administration.
12. Contrôlez les formulaires frontend et les widgets d'inscription.

Test d'acceptation après déploiement

Le pack est correctement déployé si :

• les modules s'installent correctement dans Magento 2.4.x,
• l'envoi SMTP fonctionne au niveau des comptes et du routing,
• l'inscription de l'abonné reste compatible avec la newsletter native de Magento,
• la campagne est planifiée par cron et traitée par queue consumer,
• les statuts de livraison mettent à jour les logs et les événements email,
• le panneau d'administration affiche les données opérationnelles de base,
• les points d'inscription frontend fonctionnent correctement,
• après désactivation des modules, le mécanisme de base Magento_Newsletter peut toujours fonctionner.

Remarques de déploiement

• Il est recommandé de déployer le pack complet avec une configuration SMTP et de tracking éprouvée.
• Les données étendues doivent être stockées dans leurs propres tables, sans dupliquer la table native newsletter_subscriber.
• La documentation opérationnelle du déploiement doit également couvrir la procédure de gestion des files d'attente, des webhooks et des tests de régression de la configuration administrative.

Amazon SES - création du compte et configuration pour l'intégration d'envoi

Objectif du document

Ce document décrit comment préparer un compte AWS et le service Amazon SES afin de pouvoir réaliser l'intégration d'envoi avec les modules de ce projet.

Le guide comprend :

• la création d'un compte AWS,
• l'activation d'Amazon SES,
• la vérification du domaine et de l'expéditeur,
• la sortie du sandbox,
• la préparation des identifiants,
• deux variantes d'intégration avec Magento :
  • via Amazon SES API,
  • via Amazon SES SMTP.

Remarque importante pour ce projet

Dans le code du projet, deux chemins d'intégration avec Amazon SES sont disponibles :

1. SES API dans Kowal_EmailTransport avec le type de transport ses.
2. SES SMTP dans Kowal_EmailSmtp avec le type de transport smtp.

Cela signifie qu'il est utile de préparer le compte AWS et SES une seule fois, mais que la méthode finale de raccordement à Magento dépend de la variante de déploiement choisie.

Hypothèses préalables

Avant de commencer, préparez :

• le domaine à partir duquel les messages seront envoyés, par exemple example.com,
• l'accès au DNS de ce domaine,
• l'adresse de l'expéditeur, par exemple newsletter@example.com,
• une carte bancaire ou un mode de facturation actif dans AWS,
• la décision concernant la région dans laquelle SES fonctionnera, par exemple eu-central-1 ou us-east-1.

1. Création d'un compte AWS

1. Accédez au panneau AWS : https://aws.amazon.com/
2. Créez un compte AWS.
3. Activez MFA pour le compte root.
4. N'utilisez pas les clés d'accès du compte root pour l'intégration applicative.

Pour l'intégration Magento, préparez un utilisateur IAM distinct ou des identifiants SMTP distincts, selon la variante choisie.

2. Activation d'Amazon SES

1. Connectez-vous à AWS Console.
2. Ouvrez le service Amazon Simple Email Service.
3. Sélectionnez la région dans laquelle vous souhaitez effectuer l'envoi.

C'est important, car dans SES la région a une importance opérationnelle :

• les identités d'expéditeur sont maintenues par région,
• le statut sandbox/production access s'applique à la région,
• les données de configuration Magento doivent pointer vers la même région,
• les identifiants SMTP dans SES sont uniques par région.

Si la boutique opère à l'international, il est préférable de définir immédiatement la région cible pour le marché concerné ou pour toute l'organisation, puis de s'y tenir de manière cohérente.

3. Vérification du domaine ou de l'adresse d'expéditeur

La meilleure pratique pour une boutique consiste à vérifier le domaine entier, et non une simple adresse email.

Variante recommandée

Vérifiez le domaine, par exemple example.com.

Grâce à cela :

• vous pouvez envoyer depuis plusieurs adresses de ce domaine,
• il est plus facile de passer à l'envoi en production,
• vous vous préparez mieux aux campagnes, aux emails transactionnels et à plusieurs expéditeurs,
• il est plus facile de gérer plusieurs boutiques, langues et marques dans un même écosystème.

Étapes

1. Dans SES, accédez à Identities.
2. Sélectionnez Create identity.
3. Choisissez le type Domain.
4. Saisissez le domaine d'envoi.
5. Activez Easy DKIM si vous n'avez pas de raison d'utiliser vos propres clés DKIM.
6. Ajoutez à votre zone DNS les enregistrements DNS indiqués par AWS.
7. Attendez le statut Verified.

Périmètre DNS minimal

En pratique, vous aurez besoin au minimum de :

• records de vérification SES,
• records DKIM,
• éventuellement d'un record pour custom MAIL FROM.

4. Sortie du sandbox SES

Un nouveau compte SES fonctionne généralement au départ en sandbox.

Cela signifie notamment que :

• vous pouvez envoyer uniquement depuis des identités vérifiées,
• les destinataires doivent également être vérifiés,
• vous ne pourrez pas effectuer un envoi de production normal aux clients de la boutique.

Étapes

1. Dans SES, ouvrez Account dashboard ou l'écran initial de configuration.
2. Sélectionnez l'option Request production access.
3. Remplissez le formulaire conformément à l'usage prévu du système :
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Précisez que l'envoi sera effectué depuis votre propre Magento pour une boutique en ligne.
5. Envoyez la demande.

Avant d'envoyer la demande, il est préférable d'avoir déjà un domaine vérifié. Cela accélère généralement l'approbation.

5. Configuration de la délivrabilité

Ce n'est pas le minimum obligatoire pour le premier test, mais c'est fortement recommandé avant la production.

DKIM

Si vous utilisez Easy DKIM, SES signe automatiquement les messages après une configuration DNS correcte.

Custom MAIL FROM

Si vous souhaitez améliorer le contrôle de l'expéditeur technique et la délivrabilité :

1. Ouvrez le domaine vérifié dans SES.
2. Configurez Custom MAIL FROM domain, par exemple mail.example.com.
3. Ajoutez au DNS :
   • un record MX,
   • un record SPF/TXT pour MAIL FROM.

Cela a particulièrement du sens pour les boutiques qui mènent des actions régulières d'email marketing et souhaitent limiter les problèmes de réputation d'expéditeur.

6. Variante A - intégration via Amazon SES API

Cette variante utilise le type de transport ses disponible dans Kowal_EmailTransport.

Quand choisir cette variante

Choisissez SES API si :

• vous souhaitez utiliser Amazon SES directement comme provider,
• vous souhaitez maintenir un compte de transport de type ses,
• vous souhaitez router les messages via Kowal_EmailTransport.

6.1. Création d'un utilisateur IAM pour l'envoi

N'utilisez pas le compte root.

Préparez un utilisateur IAM distinct, par exemple :

• magento-ses-sender

Attribuez-lui ensuite une politique avec les autorisations minimales nécessaires à l'envoi.

Exemple de politique minimale

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

Si vous le souhaitez, vous pouvez l'étendre à la lecture des limites ou des statistiques, mais pour l'envoi lui-même, ce périmètre constitue un point de départ.

6.2. Création de l'Access Key et de la Secret Key

1. Ouvrez IAM.
2. Accédez à Users.
3. Ouvrez l'utilisateur préparé.
4. Allez dans l'onglet Security credentials.
5. Dans la section Access keys, sélectionnez Create access key.
6. Enregistrez :
   • Access Key ID
   • Secret Access Key

Vous ne verrez le secret qu'une seule fois. Si vous le perdez, vous devrez créer une nouvelle clé.

6.3. Données nécessaires dans Magento pour la variante API

Pour le compte de transport ses dans Magento, préparez :

• provider_region, par exemple eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email en option,
• store_id, si le compte doit fonctionner uniquement pour un store view spécifique.

6.4. Mapping vers le panneau Magento

Dans Kowal / Email Marketing :

1. Ajoutez un nouveau compte de transport.
2. Définissez :
   • Transport Type = Amazon SES,
   • Region = région SES,
   • Access Key = clé IAM,
   • Secret Key = secret IAM.
3. Enregistrez le compte.
4. Associez le compte au routing des messages.
5. Effectuez un test d'envoi depuis le compte de transport.

7. Variante B - intégration via Amazon SES SMTP

Cette variante utilise Kowal_EmailSmtp.

Quand choisir cette variante

Choisissez SES SMTP si :

• vous souhaitez déployer Amazon SES comme source SMTP,
• vous utilisez le pack Advance Email Delivery,
• vous souhaitez conserver un modèle d'intégration plus simple côté Magento.

7.1. Création des identifiants SMTP dans SES

1. Ouvrez Amazon SES.
2. Accédez à SMTP settings.
3. Sélectionnez Create SMTP credentials.
4. AWS vous guidera dans la création d'un utilisateur IAM pour SMTP.
5. Enregistrez :
   • SMTP username
   • SMTP password

Il ne s'agit pas de clés AWS standard. Ce sont des identifiants SMTP distincts pour SES.

7.2. Endpoint SMTP

Pour SES, utilisez un hôte au format :

email-smtp..amazonaws.com

Exemple :

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

7.3. Port et chiffrement

Paramètres les plus couramment utilisés :

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

En pratique, pour Magento, le point de départ le plus sûr est :

• hôte : email-smtp..amazonaws.com
• port : 587
• security : STARTTLS

7.4. Données nécessaires dans Magento pour la variante SMTP

Préparez :

• l'hôte SMTP,
• le port,
• le type de chiffrement,
• le login SMTP,
• le mot de passe SMTP,
• une adresse d'expéditeur conforme à la verified identity dans SES.

7.5. Mapping vers le panneau Magento

Dans Kowal / Email Marketing :

1. Dans la section smtp, définissez globalement :
   • enabled = Yes,
   • host = endpoint SES,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = adresse de test.
2. Enregistrez la configuration.
3. Exécutez Send Test Email.

Si vous utilisez plusieurs comptes ou plusieurs store views, vous pouvez également configurer un compte de transport distinct de type smtp avec des données de connexion dédiées.

8. Que choisir dans ce projet

Choisissez SES API si :

• vous souhaitez utiliser des comptes de transport ses,
• vous souhaitez router l'envoi par compte et provider,
• vous souhaitez faire évoluer le transport sans tout baser sur la couche SMTP.

Choisissez SES SMTP si :

• vous visez un premier déploiement plus rapide,
• vous souhaitez traiter SES comme un serveur SMTP externe,
• vous déployez principalement un pack de delivery basé sur Kowal_EmailSmtp.

9. Checklist minimale avant le test d'envoi

Avant le premier test, confirmez :

1. Le compte AWS existe et la facturation est active.
2. La région SES a été choisie.
3. Le domaine ou l'adresse d'expéditeur a le statut Verified.
4. Le compte SES dispose d'un production access ou vous testez uniquement dans les conditions du sandbox.
5. DKIM est configuré.
6. Magento dispose des bonnes données d'expéditeur.
7. La variante d'intégration a été choisie :
   • API,
   • ou SMTP.
8. Les identifiants sont enregistrés en toute sécurité.
9. Un test a été envoyé et la livraison du message a été confirmée.

10. Erreurs les plus fréquentes

Le compte est toujours en sandbox

Symptôme :

• le message n'est pas envoyé à des destinataires normaux.

Cause :

• absence de production access.

Le domaine n'est pas vérifié

Symptôme :

• erreur d'expéditeur ou rejet de l'envoi.

Cause :

• absence de verified identity pour le domaine ou l'adresse d'expéditeur.

Mauvaise région

Symptôme :

• les données semblent correctes, mais l'envoi ne fonctionne toujours pas.

Cause :

• l'identité est vérifiée dans une autre région que celle utilisée par l'intégration.

Confusion entre les clés API et les identifiants SMTP

Symptôme :

• la connexion SMTP ne fonctionne pas.

Cause :

• des clés IAM ont été saisies dans SMTP au lieu de SMTP username et SMTP password.

Utilisation du compte root

Symptôme :

• absence de séparation de sécurité et rotation des identifiants plus difficile.

Cause :

• intégration basée sur les données root au lieu d'un utilisateur IAM distinct ou d'identifiants SMTP distincts.

11. Liens vers la documentation officielle 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. Données à transmettre pour le déploiement

À la fin, la personne qui configure SES doit transmettre pour le déploiement exactement cet ensemble :

Pour la variante SES API

• la région SES,
• le verified domain,
• l'access key,
• la secret key,
• l'adresse de l'expéditeur,
• le reply-to, s'il doit être différent,
• l'information indiquant si le compte doit fonctionner globalement ou par store view.

Pour la variante SES SMTP

• la région SES,
• l'hôte SMTP,
• le port,
• le mode de sécurité,
• le SMTP username,
• le SMTP password,
• l'adresse de l'expéditeur,
• l'adresse de test pour la vérification.