Guide d’installation et de configuration

1. Prérequis

Le module est destiné à Magento 2 et à une installation gérée par Composer.

Requis :

• projet Magento 2 géré par Composer,
• version de PHP compatible avec l’installation Magento utilisée,
• accès à Magento CLI,
• OpenAI API key,
• processus Magento Message Queue consumer opérationnel.

Package du module :

kowal/module-ai-email-theme-generator

Nom du module Magento :

Kowal_AiEmailThemeGenerator

2. Installation

Ajoutez le dépôt Composer :

composer config repositories.ai.email.theme.generator vcs https://github.com/kowalco/ai-email-theme-generator

Si le dépôt est privé, configurez l’authentification GitHub :

composer config --global --auth github-oauth.github.com 

Installez le module :

composer require kowal/module-ai-email-theme-generator

Activez le module :

bin/magento module:enable Kowal_AiEmailThemeGenerator

Lancez la mise à jour Magento :

bin/magento setup:upgrade

Videz le cache :

bin/magento cache:flush

Pour le mode production, exécutez les commandes de déploiement standard utilisées dans le projet, par exemple :

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3. Queue Consumer

La génération IA est traitée de manière asynchrone par Magento Message Queue.

Lancez le consumer manuellement :

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

Dans les environnements de production, configurez le consumer sous supervisor, systemd ou un autre gestionnaire de processus utilisé par l’hébergement.

Le module crée des tâches dans le panneau d’administration, mais la requête vers l’IA ne sera pas traitée tant que le consumer ne fonctionne pas.

4. Droits administrateur

Le module ajoute des ressources ACL :

Kowal_AiEmailThemeGenerator::rootKowal_AiEmailThemeGenerator::jobsKowal_AiEmailThemeGenerator::generateKowal_AiEmailThemeGenerator::retryKowal_AiEmailThemeGenerator::cancelKowal_AiEmailThemeGenerator::applyKowal_AiEmailThemeGenerator::deleteKowal_AiEmailThemeGenerator::settings

Pour qu’un administrateur puisse utiliser le module, attribuez les ressources appropriées dans :

System > Permissions > User Roles

Pour un accès complet, autorisez la ressource principale AI Email Generation ainsi que toutes les ressources enfants.

5. Emplacement de la configuration

Accédez à :

Stores > Configuration > AI Email Generation > AI Email Theme Generator

La section de configuration contient le groupe :

General Settings

6. Champs de configuration

Enabled

Type : Yes/No

Par défaut : No

Active ou désactive les fonctionnalités du module.

Lorsque la valeur est No :

• le module ne doit pas créer de tâches de génération IA,
• l’action de génération est bloquée,
• l’administrateur doit d’abord configurer le module.

Définissez Yes uniquement après avoir préparé l’API key et lancé le queue consumer.

API Provider

Type : Select

Par défaut : OpenAI

Définit le fournisseur d’IA utilisé par le module.

L’implémentation actuelle prend en charge :

OpenAI

Ce champ existe afin de permettre l’ajout futur d’autres providers sans modifier le workflow administrateur.

OpenAI API Key

Type : champ masqué/chiffré

Stocke l’OpenAI API key utilisée pour la génération.

La valeur est chiffrée par Magento à l’aide de :

MagentoConfigModelConfigBackendEncrypted

Important :

• ne placez pas l’API key directement dans le code,
• ne commitez pas les clés d’environnement,
• limitez l’accès à ce champ via ACL,
• utilisez une clé avec des droits adaptés au projet.

OpenAI Model

Type : Select

Définit le modèle OpenAI utilisé pour la génération.

Exemple :

gpt-4.1

La liste est récupérée dynamiquement depuis OpenAI Models API à l’aide de l’API key configurée. Le module filtre la réponse pour ne conserver que les identifiants de modèles GPT et met la liste en cache pendant une courte durée afin de ne pas appeler l’API à chaque ouverture de la configuration.

Si l’API key n’a pas encore été enregistrée, le champ affichera une option de secours et demandera à l’administrateur d’enregistrer la clé.

Si OpenAI API est temporairement indisponible, le champ conserve le modèle actuellement configuré, dans la mesure du possible.

Utilisez un modèle prenant en charge le type de données d’entrée requis :

• génération de texte pour les prompts et le contenu du modèle,
• modèle prenant en charge les images si des designs de référence graphiques sont utilisés.

Le modèle choisi influence la qualité du résultat, le temps de réponse et le coût.

Request Timeout

Type : Number

Exemple de valeur par défaut :

120

Temps maximal en secondes autorisé pour la requête vers OpenAI API.

Valeurs recommandées :

• 60 pour une génération de texte courte,
• 120 ou plus pour une génération HTML/CSS complexe,
• des valeurs plus élevées uniquement si l’infrastructure autorise des tâches de file d’attente plus longues.

Le timeout concerne le traitement en arrière-plan, et non la requête du formulaire d’administration.

Maximum Retries

Type : Number

Exemple de valeur par défaut :

2

Définit combien de fois le consumer peut relancer automatiquement une tâche de génération échouée.

Les relances sont utiles en cas d’erreurs temporaires, telles que :

• timeout API,
• erreur temporaire du provider,
• rate limit,
• problème réseau.

Les erreurs permanentes, par exemple une configuration incorrecte ou une réponse IA invalide, doivent être vérifiées dans les détails de la tâche.

Technical Prompt

Type : Textarea

Ce prompt est appliqué à chaque demande de génération. Il doit contenir les règles techniques qui doivent toujours être respectées.

Exemple :

You are an assistant generating Magento 2 email templates.Return only JSON that matches the provided schema.Keep Magento directives valid.Do not invent Magento variables.Do not add JavaScript.Put CSS in template_styles unless inline styles are required for email compatibility.Preserve required variables and add warnings when a requested change is risky.When assets are provided, use only the URLs from the assets section, preserve alt text, apply target links to clickable images, use banners and icons according to their sort_order, and do not invent additional image URLs.

Utilisez ce champ pour les instructions stables, telles que :

• préserver les directives Magento,
• conserver les variables requises,
• éviter JavaScript,
• renvoyer uniquement du JSON,
• écrire du HTML compatible avec les clients de messagerie,
• utiliser le CSS dans le champ de résultat approprié.

N’utilisez pas ce champ pour des instructions créatives ponctuelles. Pour cela, utilisez AI Prompt dans le formulaire du modèle.

Default User Prompt

Type : Textarea

Ce prompt est affiché par défaut dans la section IA de l’éditeur de modèles d’e-mail.

Exemple :

Improve this Magento email template while keeping all required Magento variables and directives valid.

L’administrateur peut le modifier avant de créer la tâche de génération.

Utilisez ce champ pour définir une instruction par défaut pratique pour les tâches de génération courantes.

Allowed Design File Types

Type : Text

Exemple de valeur par défaut :

png,jpg,jpeg,webp,html,htm,txt

Liste des extensions de fichiers autorisées pour le design de référence facultatif, séparées par des virgules.

Exemples pris en charge :

• png
• jpg
• jpeg
• webp
• html
• htm
• txt

En production, utilisez une liste aussi restrictive que possible. N’autorisez pas les types de fichiers qui ne sont pas nécessaires au processus.

Maximum Design File Size

Type : Number

Exemple de valeur par défaut :

5242880

Taille maximale du fichier de référence en octets.

Exemples :

• 1048576 = 1 MB
• 5242880 = 5 MB
• 10485760 = 10 MB

Les fichiers volumineux augmentent la taille du payload et peuvent ralentir la génération ou dépasser les limites du provider.

Automatically Apply Result

Type : Yes/No

Par défaut : No

Définit si un résultat IA correct doit immédiatement écraser les champs natifs du modèle Magento.

Lorsque la valeur est Yes, le consumer enregistre le résultat généré dans :

• Template Name
• Template Subject
• Template Content
• Template Styles

Lorsque la valeur est No, le résultat est conservé dans la tâche et l’administrateur peut le vérifier avant de l’appliquer manuellement.

Paramètre recommandé en production :

No

L’approbation manuelle est plus sûre, car le résultat IA peut être techniquement correct tout en nécessitant encore une revue de marque, juridique ou de layout.

Keep Request and Response Payloads

Type : Yes/No

Par défaut : Yes

Définit si le module enregistre les payloads complets de requête et de réponse dans l’enregistrement de la tâche.

Lorsque l’option est activée, les détails de la tâche peuvent afficher :

• snapshot du modèle envoyé à l’IA,
• variables disponibles,
• prompts,
• métadonnées du design de référence,
• réponse IA.

C’est utile pour le débogage et l’audit.

Dans les environnements de production, vérifiez les exigences de confidentialité avant d’activer cette option. Le module ne doit pas envoyer de données client réelles à l’IA, mais les payloads peuvent tout de même contenir du contenu de modèles sensible pour l’entreprise.

Retention Days

Type : Number

Exemple de valeur par défaut :

30

Définit la durée de conservation des anciennes tâches.

Cette valeur documente la politique de rétention cible. Le projet peut l’utiliser pour mettre en place un nettoyage périodique conforme aux exigences opérationnelles.

7. Exemple : génération du modèle New Order Confirmation for Guest

Cet exemple décrit le processus complet de génération d’un modèle d’e-mail Magento amélioré pour :

New Order Confirmation for Guest

Étape 1 : Configurez le module

Accédez à :

Stores > Configuration > AI Email Generation > AI Email Theme Generator

Définissez :

Enabled = YesAPI Provider = OpenAIOpenAI API Key = OpenAI Model = gpt-4.1Request Timeout = 120Maximum Retries = 2Automatically Apply Result = NoKeep Request and Response Payloads = Yes

Enregistrez la configuration et videz le cache si Magento vous le demande.

Étape 2 : Lancez le queue consumer

Exécutez :

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

Pendant les tests, le processus doit fonctionner en continu.

Étape 3 : Créez un modèle Magento natif

Accédez à :

Marketing > Communications > Email Templates

Cliquez sur :

Add New Template

Dans le champ Template, sélectionnez :

New Order Confirmation for Guest

Cliquez sur :

Load Template

Magento remplira les champs natifs :

• Template Subject
• Template Content
• Template Styles

Définissez le nom du modèle, par exemple :

New Order Confirmation for Guest - AI Draft

Enregistrez le modèle.

Le processus de génération IA nécessite un modèle enregistré, car la tâche doit disposer d’un template_id persistant.

Étape 4 : Renseignez l’AI Prompt

Après l’enregistrement, rouvrez le modèle si nécessaire. L’éditeur standard de modèles d’e-mail Magento contient une section AI Email Generation.

Dans le champ AI Prompt, saisissez une instruction métier, par exemple :

Create a modern, clean transactional email for a premium fashion store.Keep all Magento order variables and directives valid.Improve the subject line and make the content easier to scan.Add a clear order summary section, shipping information section, and customer support footer.Use neutral colors, simple spacing, and email-client-safe HTML.

Rôle de ce champ :

• décrit le résultat métier attendu,
• concerne uniquement la tâche de génération spécifique,
• peut contenir des instructions liées à la marque, au ton de communication, au layout ou au contenu,
• ne doit pas contenir de données API ni de données client réelles.

Étape 5 : Ajoutez éventuellement Design Reference

Utilisez Design Reference si l’e-mail généré doit suivre une direction visuelle précise.

Exemples de fichiers :

• order-email-reference.png
• brand-email-layout.webp
• email-layout.html
• design-notes.txt

Rôle de ce champ :

• fournit à l’IA un contexte visuel ou structurel supplémentaire,
• aide à adapter le modèle au design graphique,
• est facultatif,
• doit respecter les limites d’extensions et de taille de fichiers.

Si aucun design de référence n’est ajouté, l’IA utilisera uniquement le contenu du modèle, les variables, le prompt technique et le prompt utilisateur.

Étape 6 : Ajoutez éventuellement Error Screenshot

Utilisez Error Screenshot si vous souhaitez montrer à l’IA le problème actuel de rendu, de layout ou de validation du modèle.

Exemples :

• capture d’écran d’un en-tête mal aligné,
• screenshot d’un problème avec une bannière,
• aperçu d’un e-mail avec un espacement incorrect,
• capture depuis un client de messagerie montrant un problème de responsivité,
• screenshot d’un message d’erreur provenant d’un outil de test.

Ce champ est transmis à l’IA comme une section JSON distincte :

{ 'error_screenshot': { 'type': 'image', 'filename': 'email-rendering-error.png', 'mime_type': 'image/png', 'content_base64': '...', 'purpose': 'current_error_context', 'description': 'Screenshot showing current rendering, layout, visual, or validation errors. Use it to understand what should be fixed. This is not a design reference.' }}

Rôle de ce champ :

• montre à l’IA l’erreur actuelle à corriger,
• n’est pas un design graphique ni un modèle d’apparence cible,
• aide l’IA à comprendre ce qui ne fonctionne pas actuellement,
• doit être utilisé avec une description claire du problème dans AI Prompt.

Exemple de prompt :

Use the attached error screenshot only to understand the current rendering issue.Fix the spacing problem visible in the screenshot while preserving Magento variables.Do not treat the screenshot as the target design.

Étape 7 : Ajoutez des AI Assets structurés

L’éditeur contient une zone AI Assets. Ces ressources sont enregistrées avec le modèle Magento et transmises à l’IA sous forme d’URL media frontend regroupées.

Groupes de ressources disponibles :

Chaque ressource peut contenir :

Pour les bannières et les icônes, cliquez sur :

Add BannerAdd Icon

Le module enregistre les ressources envoyées dans Magento media storage et transmet à l’IA les URL frontend publiques dans la structure suivante :

{ 'assets': { 'logo': { 'label': 'Brand logo', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/logo/logo.png', 'alt': 'Brand logo', 'link': 'https://example.com/', 'sort_order': 0 }, 'header_image': { 'label': 'Spring campaign header', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/header/header.jpg', 'alt': 'Spring collection', 'link': 'https://example.com/spring', 'sort_order': 0 }, 'banners': [ { 'label': 'Main promotion', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/banner/banner.jpg', 'alt': '20% off new collection', 'link': 'https://example.com/new', 'sort_order': 10 } ], 'icons': [ { 'label': 'Free delivery', 'url': 'https://example.com/media/ai_email_theme_generator/template_12/icon/delivery.png', 'alt': 'Free delivery', 'link': 'https://example.com/delivery', 'sort_order': 10 } ] }}

Dans les prompts, faites référence directement à ces groupes. Exemple :

Use the uploaded logo as the main brand mark.Use the header image at the top of the email.Place banners below the order summary using their sort order.Use icons in a benefits row and link each icon to its target URL.Always preserve alt text.

Étape 8 : Sélectionnez la génération après enregistrement

Activez :

Generate with AI after saving

Rôle de ce champ :

• Magento enregistre d’abord le modèle avec l’action native standard save,
• après un enregistrement réussi, le module crée une tâche de génération IA,
• le design de référence envoyé est joint à la tâche,
• la tâche est traitée de manière asynchrone par le queue consumer.

Si la checkbox n’est pas cochée, l’enregistrement du modèle fonctionne exactement comme l’enregistrement standard de Magento et aucune tâche IA n’est créée.

Étape 9 : Enregistrez le modèle

Cliquez sur le bouton Magento standard :

Save Template

Après l’enregistrement du modèle, le module crée une tâche de génération.

À ce moment :

• l’enregistrement natif du modèle est terminé,
• le statut de la tâche commence par pending,
• le queue consumer traite la tâche en arrière-plan.

Étape 10 : Vérifiez la tâche

Accédez à :

Marketing > Communications > AI Email Generation Jobs

Ouvrez la tâche créée.

Champs les plus importants :

Statuts typiques :

Étape 11 : Appliquez le résultat

Si Automatically Apply Result = No, le résultat n’est pas automatiquement enregistré dans le modèle Magento.

Vérifiez :

• Template Name
• Template Subject
• Template Content
• Template Styles
• Warnings
• Request Payload
• Response Payload

Si le résultat est correct, cliquez sur :

Apply Result

Le module enregistrera les valeurs générées dans les champs natifs du modèle Magento.

Étape 12 : Vérifiez le modèle d’e-mail natif

Revenez à :

Marketing > Communications > Email Templates

Ouvrez le modèle et vérifiez que :

• Template Name a été mis à jour,
• Template Subject a été mis à jour,
• Template Content contient le HTML et les directives Magento attendus,
• Template Styles contient le CSS attendu,
• les variables Magento requises n’ont pas été supprimées.

Envoyez un message de test ou lancez un flux de commande de test conformément au processus QA standard du projet.

Étape 13 : Envoyez une nouvelle correction à l’IA

Après application du résultat via Apply Result, la version actuelle du modèle est enregistrée dans les champs natifs de Magento. Cela signifie que la prochaine demande IA s’appuiera sur cette version, et non sur le modèle d’origine.

Vous pouvez affiner plusieurs fois le même modèle :

1. Appliquez le résultat IA via Apply Result.
2. Rouvrez le modèle dans Marketing > Communications > Email Templates.
3. Saisissez un nouveau prompt décrivant la correction précise.
4. Si le problème est visuel, ajoutez Error Screenshot.
5. Cochez Generate with AI after saving.
6. Enregistrez le modèle.
7. Vérifiez la nouvelle tâche et appliquez le résultat s’il est correct.

Lors des corrections suivantes, considérez AI Prompt comme une description de modification de la version actuelle. Il est préférable d’indiquer :

• ce qui est actuellement incorrect,
• le résultat à obtenir,
• les éléments que l’IA ne doit pas modifier,
• si le Error Screenshot joint montre une erreur de rendu, une mise en page visuelle, un problème de responsivité ou un message de validation.

Exemple de prompt pour une correction ultérieure :

Use the current saved template as the base.Fix the spacing issue visible in the attached error screenshot.Keep the current header layout, all Magento variables, and the existing Template Styles structure.Do not redesign the whole email.

Ce workflow est utile lorsque la première version est proche du résultat attendu, mais nécessite un affinage de détails tels que les espacements, la responsivité, la visibilité des bannières, la position du logo ou le style des boutons.

Vous pouvez répéter ce cycle autant de fois que nécessaire. Chaque nouvelle tâche crée une entrée distincte dans l’historique, ce qui permet de revenir aux prompts, payloads et réponses IA précédents afin de vérifier quelle instruction a entraîné une modification précise.

8. Signification des champs du payload IA

Le module envoie à l’IA un payload structuré. Les sections les plus importantes sont :

template

Contient l’état actuel du modèle Magento :

• ID du modèle,
• nom du modèle,
• subject,
• content,
• styles,
• code original du modèle.

L’IA utilise cette section comme matériau de base pour la génération.

Important : si le résultat IA a déjà été appliqué via Apply Result, la section template contient déjà cette version mise à jour. La génération suivante peut ainsi fonctionner comme une correction du modèle actuel.

variables

Contient les variables et directives Magento détectées dans le modèle.

L’IA doit conserver ces valeurs et ne doit pas inventer de variables non prises en charge.

prompts

Contient :

• technical - prompt technique global issu de la configuration,
• user - prompt saisi dans l’éditeur du modèle.

Le prompt technique protège la structure propre à Magento. Le prompt utilisateur décrit le résultat attendu pour un modèle donné.

design_reference

Contient les métadonnées et le contenu facultatifs du design de référence envoyé.

La section est vide lorsqu’aucun fichier de référence n’a été envoyé.

error_screenshot

Contient un screenshot facultatif montrant les erreurs actuelles de rendu, de layout, visuelles ou de validation.

Cette section dispose d’une description purpose et description afin que l’IA sache que le fichier sert à comprendre le problème, et non de modèle pour le design cible.

La section est vide lorsqu’aucune capture d’écran n’a été envoyée.

Lors des corrections ultérieures, il est utile d’utiliser error_screenshot avec un prompt précis indiquant ce qui doit être corrigé et ce qui ne doit pas être modifié. L’IA peut ainsi corriger un problème précis sans reconstruire tout le modèle.

Exemple : après avoir appliqué le premier résultat IA, l’administrateur constate que dans Gmail, la bannière chevauche la section de résumé de commande. Dans la demande suivante, il joint un screenshot de cette vue et saisit un prompt demandant uniquement la correction des espacements et de la largeur de la bannière. Le payload contient toujours le Template Content et les Template Styles actuels, l’IA travaille donc sur la dernière version enregistrée.

assets

Contient les ressources graphiques structurées enregistrées pour le modèle :

• logo,
• header image,
• banners,
• icons.

Chaque ressource contient une URL media publique, label, alt text, target URL, sort order et filename.

L’IA doit utiliser ces URL lors de la construction du HTML et ne doit pas inventer d’adresses d’images supplémentaires.

store_context

Contient des informations de base sur la boutique, telles que :

• store ID,
• locale,
• base URL.

L’IA peut les utiliser pour comprendre la langue et le contexte, mais elle ne doit pas recevoir de données clients ou de commandes réelles.

9. Dépannage

La tâche reste au statut pending

Cause la plus probable :

• le queue consumer ne fonctionne pas.

Vérifiez :

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

La page de configuration affiche access denied

Vérifiez les droits ACL pour :

Kowal_AiEmailThemeGenerator::settings

Après modification des droits administrateur, déconnectez-vous puis reconnectez-vous.

La génération se termine par une erreur d’absence d’API key

Vérifiez :

OpenAI API Key

Assurez-vous que le module est activé et que la configuration a été enregistrée dans le bon scope.

Le résultat IA a le statut completed, mais le modèle n’a pas été mis à jour

Vérifiez :

Automatically Apply Result

Si l’option est définie sur No, ouvrez la tâche et cliquez sur :

Apply Result

La correction suivante ne prend pas en compte le résultat précédent

Vérifiez si le résultat précédent a été appliqué via :

Apply Result

La génération suivante s’appuie sur le modèle Magento actuellement enregistré. Si le résultat du job a le statut completed, mais n’a pas été appliqué, le job suivant continuera à s’appuyer sur l’ancienne version du modèle.

La réponse IA a été rejetée

Le module valide le JSON renvoyé. Il peut rejeter le résultat si :

• des champs requis sont manquants,
• les champs requis ont des types incorrects,
• le nom du modèle, subject ou content est vide,
• content contient une balise script,
• le résultat n’est pas un JSON valide.

Vérifiez le message d’erreur dans la tâche et relancez la génération avec un prompt plus clair.

10. Paramètres de production recommandés

Valeurs initiales recommandées :

Enabled = YesRequest Timeout = 120Maximum Retries = 2Automatically Apply Result = NoKeep Request and Response Payloads = Yes for testing, No or limited retention for productionRetention Days = 30

Utilisez l’application manuelle du résultat jusqu’à ce que l’équipe soit certaine que les prompts, le modèle choisi et les règles de validation produisent des modèles cohérents.