Guide d’installation et de configuration

1. Prérequis

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

Pré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 :

Les identifiants d’accès au dépôt Composer, c’est-à-dire l’adresse e-mail du client et le token de licence, vous seront envoyés par e-mail après l’achat. Ils sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine de Magento.

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

Configurez les identifiants d’accès au dépôt Composer Kowal :

composer config http-basic.repo.kowal.store "TWOJ_EMAIL_KLIENTA" "TWOJ_TOKEN"

Installez le module :

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

Activez le module :

bin/magento module:enable Kowal_AiEmailThemeGenerator

Lancez la mise à jour de Magento :

bin/magento setup:upgrade

Videz le cache :

bin/magento cache:flush

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

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3. Queue Consumer

La génération AI 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’AI ne sera pas traitée tant que le consumer ne fonctionne pas.

4. Droits administrateur

Le module ajoute des ressources ACL :

Kowal_AiEmailThemeGenerator::root
Kowal_AiEmailThemeGenerator::jobs
Kowal_AiEmailThemeGenerator::generate
Kowal_AiEmailThemeGenerator::retry
Kowal_AiEmailThemeGenerator::cancel
Kowal_AiEmailThemeGenerator::apply
Kowal_AiEmailThemeGenerator::delete
Kowal_AiEmailThemeGenerator::settings

Pour permettre à l’administrateur d’utiliser le module, attribuez les ressources appropriées dans :

System > Permissions > User Roles

Pour un accès complet, autorisez la ressource principaleAI Email Generationainsi 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 fonctions du module.

Lorsque la valeur est définie surNo:

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

DéfinissezYesuniquement 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 AI utilisé par le module.

L’implémentation actuelle prend en charge :

OpenAI

Ce champ existe afin de permettre l’ajout de nouveaux providers à l’avenir sans modifier le workflow de l’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 au moyen de :

Magento\Config\Model\Config\Backend\Encrypted

Important :

• ne placez pas l’API key directement dans le code,
• ne commitez pas de clés d’environnement,
• limitez l’accès à ce champ via ACL,
• utilisez une clé disposant 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 l’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 l’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 template,
• modèle prenant en charge les images si des projets graphiques de référence sont utilisés.

Le modèle sélectionné 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

Durée maximale en secondes autorisée pour la requête vers l’OpenAI API.

Valeurs recommandées :

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

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 nouvelles tentatives 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 AI 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 :

• conserver les directives Magento,
• maintenir les variables requises,
• éviter JavaScript,
• retourner uniquement du JSON,
• écrire du HTML compatible avec les clients e-mail,
• utiliser le CSS dans le champ de résultat approprié.

N’utilisez pas ce champ pour des instructions créatives ponctuelles. Le champAI Promptdu formulaire de template sert à cela.

Default User Prompt

Type : Textarea

Ce prompt est affiché par défaut dans la section AI de l’éditeur de template 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 une 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 projet de référence optionnel, 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 AI correct doit immédiatement écraser les champs natifs du template Magento.

Lorsque la valeur est définie surYes, le consumer enregistre le résultat généré dans :

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

Lorsque la valeur est définie surNo, 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

La validation manuelle est plus sûre, car le résultat AI peut être techniquement correct, mais nécessiter tout de même 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 template envoyé à l’AI,
• variables disponibles,
• prompts,
• métadonnées du projet de référence,
• réponse AI.

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 devrait pas envoyer de données clients réelles à l’AI, mais les payloads peuvent toujours contenir du contenu de templates sensible pour l’entreprise.

Retention Days

Type : Number

Exemple de valeur par défaut :

30

Définit la durée pendant laquelle les anciennes tâches doivent être conservées.

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

7. Exemple : génération du template New Order Confirmation for Guest

Cet exemple décrit le processus complet de génération d’un template 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 = Yes
API Provider = OpenAI
OpenAI API Key = <your OpenAI API key>
OpenAI Model = gpt-4.1
Request Timeout = 120
Maximum Retries = 2
Automatically Apply Result = No
Keep Request and Response Payloads = Yes

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

Étape 2 : Lancez le queue consumer

Lancez :

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

Pendant les tests, le processus doit fonctionner en continu.

Étape 3 : Créez un template Magento natif

Accédez à :

Marketing > Communications > Email Templates

Cliquez sur :

Add New Template

Dans le champTemplate , 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 template, par exemple :

New Order Confirmation for Guest - AI Draft

Enregistrez le template.

Le processus de génération AI nécessite un template enregistré, car la tâche doit disposer d’untemplate_id.

Étape 4 : Complétez AI Prompt

Après l’enregistrement, rouvrez le template si nécessaire. L’éditeur standard de template d’e-mail Magento contient la sectionAI Email Generation.

Dans le champAI 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 l’effet métier attendu,
• concerne uniquement une tâche de génération donnée,
• peut contenir des instructions relatives à la marque, au ton de communication, au layout ou au contenu,
• ne doit pas contenir de données API ni de données clients réelles.

Étape 5 : Ajoutez éventuellement Design Reference

UtilisezDesign Referencesi 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’AI un contexte visuel ou structurel supplémentaire,
• aide à adapter le template au projet graphique,
• est optionnel,
• doit respecter les limites d’extensions et de taille de fichiers.

Si aucun projet de référence n’est ajouté, l’AI utilisera uniquement le contenu du template, les variables, le prompt technique et le prompt utilisateur.

Étape 6 : Ajoutez éventuellement Error Screenshot

UtilisezError Screenshotsi vous souhaitez montrer à l’AI le problème actuel de rendu, de layout ou de validation du template.

Exemples :

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

Ce champ est transmis à l’AI 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’AI l’erreur actuelle à corriger,
• n’est pas un projet graphique ni un modèle d’apparence cible,
• aide l’AI à comprendre ce qui ne fonctionne pas actuellement,
• doit être utilisé avec une description claire du problème dansAI 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 zoneAI Assets. Ces ressources sont enregistrées avec le template Magento et transmises à l’AI sous forme d’URL de médias frontend regroupées.

Groupes de ressources disponibles :

Chaque ressource peut contenir :

Pour les banners et les icônes, cliquez sur :

Add Banner
Add Icon

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

{
  "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 directement référence à 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 : Choisissez la génération après enregistrement

Activez :

Generate with AI after saving

Rôle de ce champ :

• Magento enregistre d’abord le template via l’action native standard save,
• après un enregistrement réussi, le module crée une tâche de génération AI,
• le projet 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 template fonctionne exactement comme l’enregistrement standard de Magento et aucune tâche AI n’est créée.

Étape 9 : Enregistrez le template

Cliquez sur le bouton Magento standard :

Save Template

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

À ce stade :

• l’enregistrement natif du template est terminé,
• le statut de la tâche commence parpending,
• 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 courants :

Étape 11 : Appliquez le résultat

SiAutomatically Apply Result = No, le résultat n’est pas automatiquement enregistré dans le template 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 template Magento.

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

Retournez à :

Marketing > Communications > Email Templates

Ouvrez le template et vérifiez que :

• Template Name a été mis à jour,
• Template Subject a été mis à jour,
• Template Content contient le HTML attendu et les directives Magento,
• 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’AI

Après application du résultat viaApply Result, la version actuelle du template est enregistrée dans les champs natifs de Magento. Cela signifie que la demande AI suivante se basera sur cette version, et non sur le template initial.

Vous pouvez affiner plusieurs fois le même template :

1. Appliquez le résultat AI viaApply Result.
2. Rouvrez le template dansMarketing > Communications > Email Templates.
3. Saisissez un nouveau prompt décrivant la correction précise.
4. Si le problème est visuel, ajoutezError Screenshot.
5. CochezGenerate with AI after saving.
6. Enregistrez le template.
7. Vérifiez la nouvelle tâche et appliquez le résultat s’il est correct.

Pour les corrections suivantes, considérezAI Promptcomme une description de modification à appliquer à la version actuelle. Il est préférable d’indiquer :

• ce qui est actuellement incorrect,
• le résultat à obtenir,
• les éléments que l’AI ne doit pas modifier,
• si leError Screenshotjoint 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 suivante :

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 d’affiner des détails tels que les espacements, la responsivité, la visibilité des banners, la position du logo ou le style des boutons.

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

8. Signification des champs du payload AI

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

template

Contient l’état actuel du template Magento :

• ID du template,
• nom du template,
• subject,
• content,
• styles,
• code original du template.

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

Important : si un résultat AI a déjà été appliqué viaApply Result, la sectiontemplatecontient déjà cette version mise à jour. Ainsi, la génération suivante peut fonctionner comme une correction du template actuel.

variables

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

L’AI 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 de template.

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

design_reference

Contient les métadonnées optionnelles et le contenu du projet 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 optionnel montrant les erreurs actuelles de rendu, de layout, visuelles ou de validation.

Cette section comporte une descriptionpurposeetdescriptionafin que l’AI sache que le fichier sert à comprendre le problème, et non de modèle pour le projet cible.

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

Lors des corrections suivantes, il est recommandé d’utilisererror_screenshotavec un prompt précis indiquant ce qui doit être corrigé et ce qui ne doit pas être modifié. Ainsi, l’AI peut corriger un problème précis sans reconstruire tout le template.

Exemple : après avoir appliqué le premier résultat AI, l’administrateur constate que, dans Gmail, le banner 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 du banner. Le payload contient toujours leTemplate ContentetTemplate Stylesactuels, l’AI travaille donc sur la dernière version enregistrée.

assets

Contient les ressources graphiques structurées enregistrées pour le template :

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

Chaque ressource contient une URL publique de média, label, alt text, target URL, sort order et filename.

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

store_context

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

• store ID,
• locale,
• base URL.

L’AI peut les utiliser pour comprendre la langue et le contexte, mais ne doit pas recevoir de données clients ni 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 AI a le statut completed, mais le template n’a pas été mis à jour

Vérifiez :

Automatically Apply Result

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

Apply Result

La correction suivante ne tient pas compte du 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 se base sur le template Magento actuellement enregistré. Si le résultat du job a le statutcompleted, mais n’a pas été appliqué, le job suivant continuera à se baser sur une ancienne version du template.

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

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

• des champs requis sont manquants,
• les champs requis ont des types incorrects,
• le nom du template, le subject ou le content sont vides,
• le content contient la balisescript,
• 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 = Yes
Request Timeout = 120
Maximum Retries = 2
Automatically Apply Result = No
Keep Request and Response Payloads = Yes for testing, No or limited retention for production
Retention Days = 30

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