Installatie- en configuratiehandleiding

1. Vereisten

De module is bedoeld voor Magento 2 en een installatie die door 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

Naam van de Magento-module:

Kowal_AiEmailThemeGenerator

2. Installatie

Voeg de Composer-repository toe:

Toegangsgegevens voor de Composer-repository, het e-mailadres van de klant en de licentietoken, ontvangt u per e-mail na aankoop. Ze zijn ook beschikbaar in het klantpaneel na inloggen op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door de ontvangen token. Voer de opdrachten uit in de hoofdmap van Magento.

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

Configureer de toegangsgegevens voor de Composer-repository van Kowal:

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

Installeer de module:

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

Schakel de module in:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Start de Magento-update:

bin/magento setup:upgrade

Wis de cache:

bin/magento cache:flush

Voor productiemodus voert u de standaard deployment-opdrachten 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 in productieomgevingen de consumer onder supervisor, systemd of een andere procesmanager die door de hosting wordt gebruikt.

De module maakt taken aan in het beheerpaneel, maar het verzoek aan 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

Wijs de juiste resources toe in om een beheerder de module te laten gebruiken:

System > Permissions > User Roles

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

5. Configuratielocatie

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.

Stel Yes pas in 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

Dit veld bestaat zodat in de toekomst extra providers kunnen worden toegevoegd zonder de workflow van de beheerder 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:

Magento\Config\Model\Config\Backend\Encrypted

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 het antwoord tot GPT-model-ID’s en cachet de lijst korte tijd, 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 om de sleutel op te slaan.

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

Gebruik een model dat het benodigde type invoer ondersteunt:

• tekstgeneratie voor prompts en template-inhoud,
• 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 verzoek aan OpenAI API.

Aanbevolen waarden:

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

De timeout geldt voor verwerking op de achtergrond, niet voor het verzoek van het beheerformulier.

Maximum Retries

Type: Number

Voorbeeld van standaardwaarde:

2

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

Retries zijn nuttig bij tijdelijke fouten, zoals:

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

Permanente fouten, zoals onjuiste configuratie of een ongeldig AI-antwoord, moeten in de taakdetails worden gecontroleerd.

Technical Prompt

Type: Textarea

Deze prompt wordt bij elke generatieopdracht toegepast. 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:

• behouden van Magento-directives,
• behouden van verplichte 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 templateformulier.

Default User Prompt

Type: Textarea

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

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 voor typische generatietaken in te stellen.

Allowed Design File Types

Type: Text

Voorbeeld van standaardwaarde:

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

Door komma’s 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 generatie vertragen of providerlimieten overschrijden.

Automatically Apply Result

Type: Yes/No

Standaard: No

Bepaalt of een correct AI-resultaat direct de native Magento-templatevelden 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 een 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 in het taakrecord opslaat.

Wanneer de optie is ingeschakeld, kunnen taakdetails tonen:

• snapshot van de template die naar AI is verzonden,
• beschikbare variabelen,
• prompts,
• metadata van het referentieontwerp,
• AI-antwoord.

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 template-inhoud bevatten.

Retention Days

Type: Number

Voorbeeld van standaardwaarde:

30

Bepaalt hoe lang 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: template New Order Confirmation for Guest genereren

Dit voorbeeld beschrijft het volledige proces voor het genereren van een verbeterde Magento e-mailtemplate 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 draaien.

Stap 3: Maak een native Magento-template

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 templatenaam in, bijvoorbeeld:

New Order Confirmation for Guest - AI Draft

Sla de template op.

Het AI-generatieproces vereist een opgeslagen template, omdat de taak een blijvend template_id moet hebben.

Stap 4: Vul AI Prompt in

Open de template na het opslaan opnieuw, indien nodig. De standaard editor voor Magento e-mailtemplates 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 gewenste zakelijke resultaat,
• geldt alleen voor de specifieke generatietaak,
• kan instructies bevatten over merk, communicatietoon, lay-out of inhoud,
• 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 de template af te stemmen op het grafische ontwerp,
• is optioneel,
• moet voldoen aan extensie- en bestandsgroottelimieten.

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

Stap 6: Voeg optioneel Error Screenshot toe

Gebruik Error Screenshot als u AI een huidig probleem met rendering, lay-out of templatevalidatie wilt tonen.

Voorbeelden:

• screenshot van een verkeerd uitgelijnde header,
• screenshot van een bannerprobleem,
• e-mailpreview met onjuiste witruimte,
• screenshot uit een e-mailclient met een responsiviteitsprobleem,
• screenshot van een foutmelding uit een testtool.

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

{ '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 huidige fout die moet worden opgelost,
• is geen grafisch ontwerp en geen voorbeeld van de gewenste einduitstraling,
• helpt AI begrijpen wat op dit moment niet werkt,
• moet worden gebruikt samen met een duidelijke probleembeschrijving in AI Prompt.

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 de Magento-template 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: Kies genereren na opslaan

Schakel in:

Generate with AI after saving

Betekenis van dit veld:

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

Als de checkbox niet is aangevinkt, werkt het opslaan van de template precies zoals standaard opslaan in Magento en wordt er geen AI-taak aangemaakt.

Stap 9: Sla de template op

Klik op de standaard Magento-knop:

Save Template

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

Op dit moment:

• is het native opslaan van de template 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 de Magento-template.

Controleer:

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

Als het resultaat correct is, klik op:

Apply Result

De module slaat de gegenereerde waarden op in de native Magento-templatevelden.

Stap 12: Verifieer de native e-mailtemplate

Ga terug naar:

Marketing > Communications > Email Templates

Open de template 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,
• verplichte Magento-variabelen zijn niet verwijderd.

Verzend een testbericht of start een testorderflow volgens het standaard QA-proces van het project.

Stap 13: Stuur een volgende correctie naar AI

Na het toepassen van het resultaat via Apply Result wordt de huidige versie van de template opgeslagen in de native Magento-velden. Dit betekent dat de volgende AI-opdracht op deze versie wordt gebaseerd, niet op de oorspronkelijke template.

U kunt dezelfde template herhaaldelijk verfijnen:

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

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

• wat momenteel onjuist 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 details vereist zoals witruimte, responsiviteit, zichtbaarheid van banners, positie van het logo of knopstijl.

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

8. Betekenis van AI-payloadvelden

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

template

Bevat de huidige status van de Magento-template:

• template-ID,
• templatenaam,
• subject,
• content,
• styles,
• oorspronkelijke templatecode.

AI gebruikt deze sectie als basismateriaal voor generatie.

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

variables

Bevat Magento-variabelen en directives die in de template 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 template-editor.

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

design_reference

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

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

error_screenshot

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

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

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

Bij volgende correcties is het aan te raden error_screenshot te gebruiken samen met een precieze prompt die zegt wat moet worden verbeterd en wat niet mag worden gewijzigd. Daardoor kan AI een specifiek probleem oplossen zonder de hele template opnieuw op te bouwen.

Voorbeeld: na het toepassen van het eerste AI-resultaat merkt de beheerder dat in Gmail de banner over de orderoverzichtssectie valt. In de volgende opdracht voegt hij een screenshot van deze weergave toe en voert hij een prompt in die alleen vraagt om correctie van witruimte en bannerbreedte. De payload bevat nog steeds de huidige Template Content en Template Styles, dus AI werkt op de laatst opgeslagen versie.

assets

Bevat gestructureerde grafische assets die voor de template 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 store, zoals:

• store ID,
• locale,
• base URL.

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

9. Probleemoplossing

Taak blijft in status pending

Meest waarschijnlijke oorzaak:

• queue consumer draait niet.

Controleer:

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

Configuratiepagina toont access denied

Controleer ACL-rechten voor:

Kowal_AiEmailThemeGenerator::settings

Log na het wijzigen van beheerdersrechten uit en opnieuw in.

Generatie eindigt met 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.

AI-resultaat heeft status completed, maar de template is niet bijgewerkt

Controleer:

Automatically Apply Result

Als de optie op No staat, open de taak en klik op:

Apply Result

Volgende correctie houdt geen rekening met het vorige resultaat

Controleer of het vorige resultaat is toegepast via:

Apply Result

Volgende generatie wordt gebaseerd op de momenteel opgeslagen Magento-template. Als het taakresultaat de status completed heeft maar niet is toegepast, blijft de volgende taak gebaseerd op de oudere templateversie.

AI-antwoord is afgewezen

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

• verplichte velden ontbreken,
• verplichte velden onjuiste typen hebben,
• templatenaam, subject of content leeg zijn,
• content een script-tag bevat,
• het resultaat geen geldige JSON is.

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

10. Aanbevolen productie-instellingen

Aanbevolen beginwaarden:

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 handmatige toepassing van het resultaat totdat het team zeker weet dat prompts, gekozen model en validatieregels consistente templates opleveren.