Installatie- en configuratiehandleiding

1. Vereisten

De module is bedoeld voor Magento 2 en een installatie die via Composer wordt beheerd.

Vereist:

• Magento 2-project beheerd via Composer,
• PHP-versie die compatibel is met de gebruikte Magento-installatie,
• toegang tot Magento CLI,
• OpenAI API key,
• werkend Magento Message Queue consumer-proces.

Modulepakket:

kowal/module-ai-email-theme-generator

Magento-modulenaam:

Kowal_AiEmailThemeGenerator

2. Installatie

Voeg de Composer-repository toe:

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

Als de repository privé is, configureer dan GitHub-authenticatie:

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

Installeer de module:

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

Schakel de module in:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Voer de Magento-update uit:

bin/magento setup:upgrade

Wis de cache:

bin/magento cache:flush

Voer voor productiemodus de standaard deploy-commando's uit die in het project worden gebruikt, bijvoorbeeld:

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

3. Queue Consumer

AI-generatie wordt asynchroon verwerkt via Magento Message Queue.

Start de consumer handmatig:

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

Configureer de consumer in productieomgevingen onder supervisor, systemd of een andere procesmanager die door de hosting wordt gebruikt.

De module maakt taken aan in het beheerpaneel, maar de aanvraag naar AI wordt niet verwerkt zolang de consumer niet actief is.

4. Beheerdersrechten

De module voegt ACL-resources toe:

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

Om een beheerder de module te laten gebruiken, wijst u de juiste resources toe in:

System > Permissions > User Roles

Sta voor volledige toegang de hoofdresource AI Email Generation en alle onderliggende resources toe.

5. Locatie van de configuratie

Ga naar:

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

De configuratiesectie bevat de groep:

General Settings

6. Configuratievelden

Enabled

Type: Yes/No

Standaard: No

Schakelt de functies van de module in of uit.

Wanneer ingesteld op No:

• mag de module geen AI-generatietaken aanmaken,
• wordt de generatieactie geblokkeerd,
• moet de beheerder eerst de module configureren.

Zet dit pas op Yes nadat de API key is voorbereid en de queue consumer is gestart.

API Provider

Type: Select

Standaard: OpenAI

Bepaalt de AI-provider die door de module wordt gebruikt.

De huidige implementatie ondersteunt:

OpenAI

Het veld bestaat zodat in de toekomst extra providers kunnen worden toegevoegd zonder de beheerdersworkflow te wijzigen.

OpenAI API Key

Type: verborgen/versleuteld veld

Slaat de OpenAI API key op die voor generatie wordt gebruikt.

De waarde wordt door Magento versleuteld met:

MagentoConfigModelConfigBackendEncrypted

Belangrijk:

• plaats de API key niet rechtstreeks in de code,
• commit geen omgevingssleutels,
• beperk toegang tot dit veld via ACL,
• gebruik een sleutel met rechten die passend zijn voor het project.

OpenAI Model

Type: Select

Bepaalt het OpenAI-model dat voor generatie wordt gebruikt.

Voorbeeld:

gpt-4.1

De lijst wordt dynamisch opgehaald uit de OpenAI Models API met de geconfigureerde API key. De module filtert de response naar identifiers van GPT-modellen en cachet de lijst kort, zodat de API niet bij elke opening van de configuratie hoeft te worden aangeroepen.

Als de API key nog niet is opgeslagen, toont het veld een fallback-optie en vraagt het de beheerder de sleutel op te slaan.

Als de OpenAI API tijdelijk niet beschikbaar is, behoudt het veld waar mogelijk het momenteel geconfigureerde model.

Gebruik een model dat het benodigde type input ondersteunt:

• tekstgeneratie voor prompts en sjablooninhoud,
• een model dat afbeeldingen ondersteunt als grafische referentieontwerpen worden gebruikt.

Het gekozen model beïnvloedt de kwaliteit van het resultaat, de responstijd en de kosten.

Request Timeout

Type: Number

Voorbeeld van standaardwaarde:

120

Maximale tijd in seconden die is toegestaan voor een request naar de OpenAI API.

Aanbevolen waarden:

• 60 voor korte tekstgeneratie,
• 120 of meer voor complexe HTML/CSS-generatie,
• hogere waarden alleen wanneer de infrastructuur langere queue-taken toestaat.

De timeout geldt voor achtergrondverwerking, niet voor de request van het beheerformulier.

Maximum Retries

Type: Number

Voorbeeld van standaardwaarde:

2

Bepaalt hoe vaak de consumer een mislukte generatietaak automatisch opnieuw mag proberen.

Retries zijn nuttig bij tijdelijke fouten, zoals:

• API-timeout,
• tijdelijke providerfout,
• rate limit,
• netwerkprobleem.

Permanente fouten, bijvoorbeeld onjuiste configuratie of een ongeldige AI-response, moeten in de taakdetails worden gecontroleerd.

Technical Prompt

Type: Textarea

Deze prompt wordt toegepast bij elke generatieopdracht. Hij moet technische regels bevatten die altijd behouden moeten blijven.

Voorbeeld:

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.

Gebruik dit veld voor stabiele instructies, zoals:

• behoud van Magento-directives,
• behoud van vereiste variabelen,
• vermijden van JavaScript,
• uitsluitend JSON retourneren,
• HTML schrijven die compatibel is met e-mailclients,
• CSS gebruiken in het juiste resultaatveld.

Gebruik dit veld niet voor eenmalige creatieve instructies. Daarvoor dient AI Prompt in het sjabloonformulier.

Default User Prompt

Type: Textarea

Deze prompt wordt standaard getoond in de AI-sectie van de editor voor e-mailsjablonen.

Voorbeeld:

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

De beheerder kan deze wijzigen voordat een generatietaak wordt aangemaakt.

Gebruik dit veld om een praktische standaardinstructie in te stellen voor typische generatietaken.

Allowed Design File Types

Type: Text

Voorbeeld van standaardwaarde:

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

Komma-gescheiden lijst met toegestane bestandsextensies voor het optionele referentieontwerp.

Ondersteunde voorbeelden:

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

Gebruik in productie een zo restrictief mogelijke lijst. Sta geen bestandstypen toe die niet nodig zijn in het proces.

Maximum Design File Size

Type: Number

Voorbeeld van standaardwaarde:

5242880

Maximale grootte van het referentiebestand in bytes.

Voorbeelden:

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

Grote bestanden vergroten de payload en kunnen de generatie vertragen of providerlimieten overschrijden.

Automatically Apply Result

Type: Yes/No

Standaard: No

Bepaalt of een correct AI-resultaat direct de native Magento-sjabloonvelden moet overschrijven.

Wanneer ingesteld op Yes, slaat de consumer het gegenereerde resultaat op in:

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

Wanneer ingesteld op No, wordt het resultaat in de taak opgeslagen en kan de beheerder het controleren voordat het handmatig wordt toegepast.

Aanbevolen productie-instelling:

No

Handmatige goedkeuring is veiliger, omdat het AI-resultaat technisch correct kan zijn maar nog steeds een merk-, juridische of lay-outreview kan vereisen.

Keep Request and Response Payloads

Type: Yes/No

Standaard: Yes

Bepaalt of de module volledige request- en response-payloads opslaat in het taakrecord.

Wanneer de optie is ingeschakeld, kunnen taakdetails tonen:

• sjabloonsnapshot die naar AI is verzonden,
• beschikbare variabelen,
• prompts,
• metadata van het referentieontwerp,
• AI-response.

Dit is nuttig voor debugging en audit.

Controleer in productieomgevingen de privacyvereisten voordat u deze optie inschakelt. De module zou geen echte klantgegevens naar AI moeten sturen, maar payloads kunnen nog steeds bedrijfsgevoelige sjablooninhoud bevatten.

Retention Days

Type: Number

Voorbeeld van standaardwaarde:

30

Bepaalt hoelang oude taken moeten worden bewaard.

Deze waarde documenteert het beoogde retentiebeleid. Het project kan deze gebruiken om periodieke opschoning te implementeren volgens operationele vereisten.

7. Voorbeeld: een sjabloon New Order Confirmation for Guest genereren

Dit voorbeeld beschrijft het volledige proces voor het genereren van een verbeterd Magento e-mailsjabloon voor:

New Order Confirmation for Guest

Stap 1: Configureer de module

Ga naar:

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

Stel in:

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

Sla de configuratie op en wis de cache als Magento daarom vraagt.

Stap 2: Start de queue consumer

Voer uit:

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

Tijdens tests moet het proces continu actief zijn.

Stap 3: Maak een native Magento-sjabloon

Ga naar:

Marketing > Communications > Email Templates

Klik op:

Add New Template

Kies in het veld Template:

New Order Confirmation for Guest

Klik op:

Load Template

Magento vult de native velden aan:

• Template Subject
• Template Content
• Template Styles

Stel de sjabloonnaam in, bijvoorbeeld:

New Order Confirmation for Guest - AI Draft

Sla het sjabloon op.

Het AI-generatieproces vereist een opgeslagen sjabloon, omdat de taak een permanente template_id moet hebben.

Stap 4: Vul AI Prompt in

Open het sjabloon na het opslaan opnieuw indien nodig. De standaard Magento-editor voor e-mailsjablonen bevat de sectie AI Email Generation.

Voer in het veld AI Prompt een zakelijke instructie in, bijvoorbeeld:

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.

Betekenis van dit veld:

• beschrijft het verwachte zakelijke resultaat,
• geldt alleen voor deze specifieke generatietaak,
• kan instructies bevatten over merk, communicatietoon, lay-out of content,
• mag geen API-gegevens of echte klantgegevens bevatten.

Stap 5: Voeg optioneel Design Reference toe

Gebruik Design Reference als de gegenereerde e-mail een specifieke visuele richting moet volgen.

Voorbeeldbestanden:

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

Betekenis van dit veld:

• geeft AI extra visuele of structurele context,
• helpt het sjabloon af te stemmen op het grafische ontwerp,
• is optioneel,
• moet voldoen aan de limieten voor extensies en bestandsgrootte.

Als geen referentieontwerp wordt toegevoegd, gebruikt AI alleen de sjablooninhoud, variabelen, technische prompt en gebruikersprompt.

Stap 6: Voeg optioneel Error Screenshot toe

Gebruik Error Screenshot als u AI het huidige probleem met rendering, lay-out of sjabloonvalidatie wilt tonen.

Voorbeelden:

• screenshot van een slecht uitgelijnde header,
• screenshot van een probleem met een banner,
• e-mailpreview met onjuiste afstand,
• screenshot uit een e-mailclient dat een responsiviteitsprobleem toont,
• screenshot van een foutmelding uit een testtool.

Dit veld wordt aan AI doorgegeven als aparte JSON-sectie:

{ '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.' }}

Betekenis van dit veld:

• toont AI de actuele fout die moet worden opgelost,
• is geen grafisch ontwerp en geen voorbeeld van de gewenste eindweergave,
• helpt AI begrijpen wat momenteel niet werkt,
• moet samen met een duidelijke probleemomschrijving in AI Prompt worden gebruikt.

Voorbeeldprompt:

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.

Stap 7: Voeg gestructureerde AI Assets toe

De editor bevat het gebied AI Assets. Deze assets worden bij het Magento-sjabloon opgeslagen en aan AI doorgegeven als gegroepeerde frontend-media-URL's.

Beschikbare assetgroepen:

Elke asset kan bevatten:

Klik voor banners en iconen op:

Add BannerAdd Icon

De module slaat geüploade assets op in Magento media storage en geeft publieke frontend-URL's door aan AI in de structuur:

{ '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 } ] }}

Verwijs in prompts rechtstreeks naar deze groepen. Voorbeeld:

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.

Stap 8: Selecteer genereren na opslaan

Schakel in:

Generate with AI after saving

Betekenis van dit veld:

• Magento slaat het sjabloon eerst op via de standaard native save-actie,
• na correct opslaan maakt de module een AI-generatietaak aan,
• het geüploade referentieontwerp wordt aan de taak gekoppeld,
• de taak wordt asynchroon verwerkt door de queue consumer.

Als de checkbox niet is aangevinkt, werkt het opslaan van het sjabloon precies als de standaard Magento-save en wordt er geen AI-taak aangemaakt.

Stap 9: Sla het sjabloon op

Klik op de standaard Magento-knop:

Save Template

Na het opslaan van het sjabloon maakt de module een generatietaak aan.

Op dit moment:

• is de native opslag van het sjabloon voltooid,
• begint de taakstatus met pending,
• verwerkt de queue consumer de taak op de achtergrond.

Stap 10: Controleer de taak

Ga naar:

Marketing > Communications > AI Email Generation Jobs

Open de aangemaakte taak.

Belangrijkste velden:

Typische statussen:

Stap 11: Pas het resultaat toe

Als Automatically Apply Result = No, wordt het resultaat niet automatisch opgeslagen in het Magento-sjabloon.

Controleer:

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

Als het resultaat correct is, klikt u op:

Apply Result

De module slaat de gegenereerde waarden op in de native velden van het Magento-sjabloon.

Stap 12: Verifieer het native e-mailsjabloon

Ga terug naar:

Marketing > Communications > Email Templates

Open het sjabloon en controleer:

• Template Name is bijgewerkt,
• Template Subject is bijgewerkt,
• Template Content bevat de verwachte HTML en Magento-directives,
• Template Styles bevat de verwachte CSS,
• vereiste Magento-variabelen zijn niet verwijderd.

Verstuur een testbericht of start een testbestelflow volgens het standaard QA-proces van het project.

Stap 13: Verstuur een volgende correctie naar AI

Na toepassing van het resultaat via Apply Result is de actuele versie van het sjabloon opgeslagen in de native Magento-velden. Dit betekent dat een volgende AI-opdracht op deze versie is gebaseerd en niet op het oorspronkelijke sjabloon.

U kunt hetzelfde sjabloon herhaaldelijk verfijnen:

1. Pas het AI-resultaat toe via Apply Result.
2. Open het sjabloon opnieuw in Marketing > Communications > Email Templates.
3. Voer een nieuwe prompt in die een specifieke correctie beschrijft.
4. Als het probleem visueel is, voeg dan Error Screenshot toe.
5. Vink Generate with AI after saving aan.
6. Sla het sjabloon op.
7. Controleer de nieuwe taak en pas het resultaat toe als het correct is.

Behandel AI Prompt bij volgende correcties als een beschrijving van de wijziging ten opzichte van de huidige versie. Het is het beste om aan te geven:

• wat momenteel fout is,
• welk resultaat moet worden bereikt,
• welke elementen AI niet mag wijzigen,
• of de bijgevoegde Error Screenshot een renderingfout, visuele lay-out, responsiviteitsprobleem of validatiemelding toont.

Voorbeeldprompt voor een volgende correctie:

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.

Deze workflow is nuttig wanneer de eerste versie dicht bij het gewenste resultaat ligt, maar nog verfijning vereist, zoals afstand, responsiviteit, zichtbaarheid van banners, logopositie of knopstijl.

U kunt deze cyclus meerdere keren herhalen. Elke nieuwe taak maakt een aparte vermelding in de geschiedenis aan, zodat u kunt terugkeren naar eerdere prompts, payloads en AI-responses om te controleren welke instructie tot een specifieke wijziging heeft geleid.

8. Betekenis van AI-payloadvelden

De module verzendt een gestructureerde payload naar AI. De belangrijkste secties zijn:

template

Bevat de actuele staat van het Magento-sjabloon:

• sjabloon-ID,
• sjabloonnaam,
• subject,
• content,
• styles,
• originele sjablooncode.

AI gebruikt deze sectie als basismateriaal voor generatie.

Belangrijk: als het AI-resultaat eerder via Apply Result is toegepast, bevat de sectie template al deze bijgewerkte versie. Daardoor kan de volgende generatie werken als correctie op het actuele sjabloon.

variables

Bevat Magento-variabelen en -directives die in het sjabloon zijn gedetecteerd.

AI moet deze waarden behouden en mag geen niet-ondersteunde variabelen verzinnen.

prompts

Bevat:

• technical - globale technische prompt uit de configuratie,
• user - prompt ingevoerd in de sjablooneditor.

De technische prompt beschermt de Magento-specifieke structuur. De gebruikersprompt beschrijft het verwachte resultaat voor één sjabloon.

design_reference

Bevat optionele metadata en inhoud van het geüploade referentieontwerp.

De sectie is leeg wanneer geen referentiebestand is geüpload.

error_screenshot

Bevat een optionele screenshot die actuele rendering-, lay-out-, visuele of validatiefouten toont.

Deze sectie heeft een purpose en description, zodat AI weet dat het bestand dient om het probleem te begrijpen en niet als voorbeeld van het doelontwerp.

De sectie is leeg wanneer geen screenshot is geüpload.

Bij volgende correcties is het nuttig om error_screenshot te gebruiken samen met een precieze prompt die aangeeft wat moet worden opgelost en wat niet mag worden gewijzigd. Zo kan AI een concreet probleem oplossen zonder het hele sjabloon opnieuw op te bouwen.

Voorbeeld: na toepassing van het eerste AI-resultaat merkt de beheerder dat in Gmail de banner over de sectie met besteloverzicht heen valt. In de volgende opdracht voegt hij een screenshot van deze weergave toe en voert hij een prompt in die uitsluitend vraagt om herstel van afstanden en bannerbreedte. De payload bevat nog steeds de actuele Template Content en Template Styles, zodat AI werkt op de laatst opgeslagen versie.

assets

Bevat gestructureerde grafische assets die voor het sjabloon zijn opgeslagen:

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

Elke asset bevat een publieke media-URL, label, alt text, target URL, sort order en filename.

AI moet deze URL's gebruiken bij het bouwen van HTML en mag geen extra afbeeldingsadressen verzinnen.

store_context

Bevat basisinformatie over de winkel, zoals:

• store ID,
• locale,
• base URL.

AI kan deze gebruiken om de taal en context te begrijpen, maar mag geen echte klant- of bestelgegevens ontvangen.

9. Probleemoplossing

De taak blijft in status pending

Meest waarschijnlijke oorzaak:

• de queue consumer draait niet.

Controleer:

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

De configuratiepagina toont access denied

Controleer ACL-rechten voor:

Kowal_AiEmailThemeGenerator::settings

Log na het wijzigen van beheerdersrechten uit en opnieuw in.

Generatie eindigt met een fout over ontbrekende API key

Controleer:

OpenAI API Key

Zorg ervoor dat de module is ingeschakeld en de configuratie in de juiste scope is opgeslagen.

Het AI-resultaat heeft status completed, maar het sjabloon is niet bijgewerkt

Controleer:

Automatically Apply Result

Als de optie is ingesteld op No, open dan de taak en klik op:

Apply Result

Een volgende correctie houdt geen rekening met het vorige resultaat

Controleer of het vorige resultaat is toegepast via:

Apply Result

Volgende generatie is gebaseerd op het momenteel opgeslagen Magento-sjabloon. Als het jobresultaat status completed heeft maar niet is toegepast, blijft de volgende job gebaseerd op de oudere sjabloonversie.

De AI-response is geweigerd

De module valideert de geretourneerde JSON. Het resultaat kan worden geweigerd als:

• vereiste velden ontbreken,
• vereiste velden onjuiste types hebben,
• sjabloonnaam, subject of content leeg zijn,
• content een script-tag bevat,
• het resultaat geen geldige JSON is.

Controleer de foutmelding in de taak en herhaal de generatie met een duidelijkere prompt.

10. Aanbevolen productie-instellingen

Aanbevolen startwaarden:

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

Gebruik handmatig toepassen van het resultaat totdat het team zeker weet dat de prompts, het gekozen model en de validatieregels consistente sjablonen opleveren.