Guida all’installazione e alla configurazione

1. Requisiti

Il modulo è destinato a Magento 2 e a installazioni gestite tramite Composer.

Requisiti:

• progetto Magento 2 gestito tramite Composer,
• versione PHP compatibile con l’installazione Magento utilizzata,
• accesso a Magento CLI,
• OpenAI API key,
• processo Magento Message Queue consumer funzionante.

Pacchetto del modulo:

kowal/module-ai-email-theme-generator

Nome del modulo Magento:

Kowal_AiEmailThemeGenerator

2. Installazione

Aggiungi il repository Composer:

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

Se il repository è privato, configura l’autenticazione GitHub:

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

Installa il modulo:

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

Abilita il modulo:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Esegui l’aggiornamento Magento:

bin/magento setup:upgrade

Svuota la cache:

bin/magento cache:flush

Per la modalità produzione, esegui i comandi di deployment standard usati nel progetto, ad esempio:

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

3. Queue Consumer

La generazione AI viene elaborata in modo asincrono tramite Magento Message Queue.

Avvia manualmente il consumer:

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

Negli ambienti di produzione configura il consumer con supervisor, systemd o un altro gestore di processi usato dall’hosting.

Il modulo crea attività nel pannello di amministrazione, ma la richiesta verso l’AI non verrà elaborata finché il consumer non sarà in esecuzione.

4. Permessi amministratore

Il modulo aggiunge risorse ACL:

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

Affinché l’amministratore possa usare il modulo, assegna le risorse appropriate in:

System > Permissions > User Roles

Per l’accesso completo, consenti la risorsa principale AI Email Generation e tutte le risorse figlie.

5. Posizione della configurazione

Vai a:

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

La sezione di configurazione contiene il gruppo:

General Settings

6. Campi di configurazione

Enabled

Tipo: Yes/No

Predefinito: No

Abilita o disabilita le funzioni del modulo.

Quando è impostato su No:

• il modulo non dovrebbe creare attività di generazione AI,
• l’azione di generazione è bloccata,
• l’amministratore dovrebbe prima configurare il modulo.

Imposta Yes solo dopo aver preparato l’API key e avviato il queue consumer.

API Provider

Tipo: Select

Predefinito: OpenAI

Definisce il provider AI utilizzato dal modulo.

L’implementazione attuale supporta:

OpenAI

Il campo esiste per consentire in futuro l’aggiunta di altri provider senza modificare il workflow dell’amministratore.

OpenAI API Key

Tipo: campo nascosto/cifrato

Archivia l’OpenAI API key utilizzata per la generazione.

Il valore viene cifrato da Magento usando:

MagentoConfigModelConfigBackendEncrypted

Importante:

• non inserire l’API key direttamente nel codice,
• non committare chiavi di ambiente,
• limita l’accesso a questo campo tramite ACL,
• usa una chiave con permessi adeguati al progetto.

OpenAI Model

Tipo: Select

Definisce il modello OpenAI utilizzato per la generazione.

Esempio:

gpt-4.1

L’elenco viene recuperato dinamicamente da OpenAI Models API usando l’API key configurata. Il modulo filtra la risposta sugli identificatori dei modelli GPT e memorizza l’elenco in cache per un breve periodo, così da non chiamare l’API a ogni apertura della configurazione.

Se l’API key non è ancora stata salvata, il campo mostrerà un’opzione di fallback e chiederà all’amministratore di salvare la chiave.

Se OpenAI API è temporaneamente non disponibile, il campo mantiene il modello attualmente configurato, se possibile.

Usa un modello che supporti il tipo di input necessario:

• generazione testuale per prompt e contenuto del template,
• modello con supporto immagini se vengono usati progetti grafici di riferimento.

Il modello selezionato influisce sulla qualità del risultato, sul tempo di risposta e sul costo.

Request Timeout

Tipo: Number

Esempio di valore predefinito:

120

Tempo massimo in secondi consentito per la richiesta a OpenAI API.

Valori consigliati:

• 60 per generazioni testuali brevi,
• 120 o più per generazioni HTML/CSS complesse,
• valori più alti solo se l’infrastruttura consente attività in coda più lunghe.

Il timeout riguarda l’elaborazione in background, non la richiesta del form amministrativo.

Maximum Retries

Tipo: Number

Esempio di valore predefinito:

2

Definisce quante volte il consumer può riprovare automaticamente un’attività di generazione non riuscita.

I retry sono utili in caso di errori temporanei, come:

• timeout API,
• errore temporaneo del provider,
• rate limit,
• problema di rete.

Gli errori permanenti, ad esempio configurazione errata o risposta AI non valida, devono essere verificati nei dettagli dell’attività.

Technical Prompt

Tipo: Textarea

Questo prompt viene applicato a ogni richiesta di generazione. Dovrebbe contenere regole tecniche che devono essere sempre rispettate.

Esempio:

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.

Usa questo campo per istruzioni stabili, come:

• preservare le direttive Magento,
• mantenere le variabili richieste,
• evitare JavaScript,
• restituire esclusivamente JSON,
• scrivere HTML compatibile con i client di posta,
• usare il CSS nel campo corretto del risultato.

Non usare questo campo per istruzioni creative una tantum. A questo serve AI Prompt nel form del template.

Default User Prompt

Tipo: Textarea

Questo prompt viene mostrato per impostazione predefinita nella sezione AI dell’editor del template email.

Esempio:

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

L’amministratore può modificarlo prima di creare l’attività di generazione.

Usa questo campo per impostare un’istruzione predefinita pratica per attività di generazione tipiche.

Allowed Design File Types

Tipo: Text

Esempio di valore predefinito:

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

Elenco delle estensioni file consentite per il progetto di riferimento opzionale, separate da virgole.

Esempi supportati:

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

In produzione usa un elenco il più restrittivo possibile. Non consentire tipi di file non necessari nel processo.

Maximum Design File Size

Tipo: Number

Esempio di valore predefinito:

5242880

Dimensione massima del file di riferimento in byte.

Esempi:

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

I file grandi aumentano la dimensione del payload e possono rallentare la generazione o superare i limiti del provider.

Automatically Apply Result

Tipo: Yes/No

Predefinito: No

Definisce se un risultato AI valido deve sovrascrivere subito i campi nativi del template Magento.

Quando è impostato su Yes, il consumer salva il risultato generato in:

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

Quando è impostato su No, il risultato viene conservato nell’attività e l’amministratore può verificarlo prima di applicarlo manualmente.

Impostazione consigliata in produzione:

No

L’approvazione manuale è più sicura, perché il risultato AI può essere tecnicamente corretto ma richiedere comunque una revisione di brand, legale o di layout.

Keep Request and Response Payloads

Tipo: Yes/No

Predefinito: Yes

Definisce se il modulo salva i payload completi di richiesta e risposta nel record dell’attività.

Quando l’opzione è abilitata, i dettagli dell’attività possono mostrare:

• snapshot del template inviato all’AI,
• variabili disponibili,
• prompt,
• metadati del progetto di riferimento,
• risposta AI.

È utile per debug e audit.

Negli ambienti di produzione verifica i requisiti di privacy prima di abilitare questa opzione. Il modulo non dovrebbe inviare dati reali dei clienti all’AI, ma i payload possono comunque contenere contenuti dei template sensibili per il business.

Retention Days

Tipo: Number

Esempio di valore predefinito:

30

Definisce per quanto tempo le vecchie attività devono essere conservate.

Questo valore documenta la policy di retention prevista. Il progetto può usarlo per implementare una pulizia periodica in base ai requisiti operativi.

7. Esempio: generazione del template New Order Confirmation for Guest

Questo esempio descrive l’intero processo di generazione di un template email Magento migliorato per:

New Order Confirmation for Guest

Passaggio 1: Configura il modulo

Vai a:

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

Imposta:

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

Salva la configurazione e svuota la cache se Magento lo richiede.

Passaggio 2: Avvia il queue consumer

Esegui:

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

Durante i test, il processo dovrebbe rimanere sempre attivo.

Passaggio 3: Crea un template Magento nativo

Vai a:

Marketing > Communications > Email Templates

Fai clic su:

Add New Template

Nel campo Template seleziona:

New Order Confirmation for Guest

Fai clic su:

Load Template

Magento compilerà i campi nativi:

• Template Subject
• Template Content
• Template Styles

Imposta il nome del template, ad esempio:

New Order Confirmation for Guest - AI Draft

Salva il template.

Il processo di generazione AI richiede un template salvato, perché l’attività deve avere un template_id persistente.

Passaggio 4: Compila AI Prompt

Dopo il salvataggio, riapri il template se necessario. L’editor standard dei template email Magento include la sezione AI Email Generation.

Nel campo AI Prompt inserisci un’istruzione business, ad esempio:

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.

Significato di questo campo:

• descrive il risultato business atteso,
• riguarda solo la specifica attività di generazione,
• può contenere istruzioni relative a brand, tono di comunicazione, layout o contenuto,
• non dovrebbe contenere dati API né dati reali dei clienti.

Passaggio 5: Aggiungi opzionalmente Design Reference

Usa Design Reference se l’email generata deve seguire una specifica direzione visiva.

File di esempio:

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

Significato di questo campo:

• fornisce all’AI un contesto visivo o strutturale aggiuntivo,
• aiuta ad adattare il template al progetto grafico,
• è opzionale,
• deve rispettare i limiti di estensione e dimensione dei file.

Se non viene aggiunto un progetto di riferimento, l’AI userà solo contenuto del template, variabili, prompt tecnico e prompt utente.

Passaggio 6: Aggiungi opzionalmente Error Screenshot

Usa Error Screenshot se vuoi mostrare all’AI un problema attuale di rendering, layout o validazione del template.

Esempi:

• screenshot di un’intestazione allineata male,
• screenshot di un problema con il banner,
• anteprima dell’email con spaziatura errata,
• screenshot da un client di posta che mostra un problema di responsività,
• screenshot di un messaggio di errore da uno strumento di test.

Questo campo viene passato all’AI come sezione JSON separata:

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

Significato di questo campo:

• mostra all’AI l’errore attuale da correggere,
• non è un progetto grafico né un modello dell’aspetto finale,
• aiuta l’AI a capire cosa attualmente non funziona,
• dovrebbe essere usato insieme a una descrizione chiara del problema in AI Prompt.

Esempio di 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.

Passaggio 7: Aggiungi AI Assets strutturati

L’editor include l’area AI Assets. Queste risorse vengono salvate con il template Magento e passate all’AI come URL media frontend raggruppati.

Gruppi di risorse disponibili:

Ogni risorsa può contenere:

Per banner e icone fai clic su:

Add BannerAdd Icon

Il modulo salva le risorse caricate nel Magento media storage e passa all’AI URL frontend pubblici nella struttura:

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

Nei prompt fai riferimento direttamente a questi gruppi. Esempio:

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.

Passaggio 8: Seleziona la generazione dopo il salvataggio

Abilita:

Generate with AI after saving

Significato di questo campo:

• Magento salva prima il template con l’azione save nativa standard,
• dopo un salvataggio corretto, il modulo crea un’attività di generazione AI,
• il progetto di riferimento caricato viene allegato all’attività,
• l’attività viene elaborata in modo asincrono dal queue consumer.

Se la checkbox non è selezionata, il salvataggio del template funziona esattamente come il salvataggio standard di Magento e non viene creata alcuna attività AI.

Passaggio 9: Salva il template

Fai clic sul pulsante standard Magento:

Save Template

Dopo il salvataggio del template, il modulo crea l’attività di generazione.

A questo punto:

• il salvataggio nativo del template è completato,
• lo stato dell’attività inizia da pending,
• il queue consumer elabora l’attività in background.

Passaggio 10: Controlla l’attività

Vai a:

Marketing > Communications > AI Email Generation Jobs

Apri l’attività creata.

Campi più importanti:

Stati tipici:

Passaggio 11: Applica il risultato

Se Automatically Apply Result = No, il risultato non viene salvato automaticamente nel template Magento.

Controlla:

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

Se il risultato è corretto, fai clic su:

Apply Result

Il modulo salverà i valori generati nei campi nativi del template Magento.

Passaggio 12: Verifica il template email nativo

Torna a:

Marketing > Communications > Email Templates

Apri il template e controlla:

• Template Name è stato aggiornato,
• Template Subject è stato aggiornato,
• Template Content contiene l’HTML atteso e le direttive Magento,
• Template Styles contiene il CSS atteso,
• le variabili Magento richieste non sono state rimosse.

Invia un messaggio di test oppure esegui un flusso d’ordine di test secondo il processo QA standard del progetto.

Passaggio 13: Invia un’altra correzione all’AI

Dopo aver applicato il risultato tramite Apply Result, la versione attuale del template viene salvata nei campi nativi di Magento. Questo significa che la successiva richiesta AI si baserà su questa versione e non sul template iniziale.

Puoi perfezionare più volte lo stesso template:

1. Applica il risultato AI tramite Apply Result.
2. Riapri il template in Marketing > Communications > Email Templates.
3. Inserisci un nuovo prompt che descriva la correzione specifica.
4. Se il problema è visivo, aggiungi Error Screenshot.
5. Seleziona Generate with AI after saving.
6. Salva il template.
7. Controlla la nuova attività e applica il risultato se è corretto.

Nelle correzioni successive, tratta AI Prompt come descrizione della modifica alla versione attuale. È meglio indicare:

• cosa è attualmente errato,
• quale risultato deve essere ottenuto,
• quali elementi l’AI non dovrebbe modificare,
• se l’Error Screenshot allegato mostra un errore di rendering, un layout visivo, un problema di responsività o un messaggio di validazione.

Prompt di esempio per una correzione successiva:

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.

Questo workflow è utile quando la prima versione è vicina al risultato atteso ma richiede la rifinitura di dettagli come spaziature, responsività, visibilità dei banner, posizione del logo o stile dei pulsanti.

Puoi ripetere questo ciclo più volte. Ogni nuova attività crea una voce separata nella cronologia, quindi è possibile tornare ai prompt, ai payload e alle risposte AI precedenti per verificare quale istruzione ha portato a una specifica modifica.

8. Significato dei campi del payload AI

Il modulo invia all’AI un payload strutturato. Le sezioni più importanti sono:

template

Contiene lo stato attuale del template Magento:

• ID del template,
• nome del template,
• subject,
• content,
• styles,
• codice originale del template.

L’AI usa questa sezione come materiale di base per la generazione.

Importante: se in precedenza è stato applicato un risultato AI tramite Apply Result, la sezione template contiene già questa versione aggiornata. In questo modo la generazione successiva può funzionare come correzione del template attuale.

variables

Contiene variabili e direttive Magento rilevate nel template.

L’AI deve preservare questi valori e non deve inventare variabili non supportate.

prompts

Contiene:

• technical - prompt tecnico globale dalla configurazione,
• user - prompt inserito nell’editor del template.

Il prompt tecnico protegge la struttura specifica di Magento. Il prompt utente descrive il risultato atteso per un singolo template.

design_reference

Contiene metadati opzionali e contenuto del progetto di riferimento caricato.

La sezione è vuota quando non viene caricato alcun file di riferimento.

error_screenshot

Contiene uno screenshot opzionale che mostra errori attuali di rendering, layout, visivi o di validazione.

Questa sezione contiene purpose e description affinché l’AI sappia che il file serve a comprendere il problema e non come modello del progetto finale.

La sezione è vuota quando non viene caricato alcuno screenshot.

Nelle correzioni successive conviene usare error_screenshot insieme a un prompt preciso che indichi cosa deve essere corretto e cosa non deve essere modificato. In questo modo l’AI può risolvere un problema specifico senza ricostruire l’intero template.

Esempio: dopo aver applicato il primo risultato AI, l’amministratore nota che in Gmail il banner si sovrappone alla sezione di riepilogo dell’ordine. Nella richiesta successiva allega uno screenshot di questa visualizzazione e inserisce un prompt che chiede esclusivamente di correggere spaziature e larghezza del banner. Il payload contiene ancora gli attuali Template Content e Template Styles, quindi l’AI lavora sull’ultima versione salvata.

assets

Contiene le risorse grafiche strutturate salvate per il template:

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

Ogni risorsa contiene URL media pubblico, label, alt text, target URL, sort order e filename.

L’AI dovrebbe usare questi URL durante la costruzione dell’HTML e non dovrebbe inventare indirizzi immagine aggiuntivi.

store_context

Contiene informazioni di base sul negozio, come:

• store ID,
• locale,
• base URL.

L’AI può usarle per comprendere lingua e contesto, ma non dovrebbe ricevere dati reali di clienti o ordini.

9. Risoluzione dei problemi

L’attività rimane nello stato pending

Causa più probabile:

• il queue consumer non è in esecuzione.

Controlla:

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

La pagina di configurazione mostra access denied

Controlla i permessi ACL per:

Kowal_AiEmailThemeGenerator::settings

Dopo aver modificato i permessi amministratore, effettua il logout e accedi di nuovo.

La generazione termina con un errore di API key mancante

Controlla:

OpenAI API Key

Assicurati che il modulo sia abilitato e che la configurazione sia stata salvata nello scope corretto.

Il risultato AI ha stato completed, ma il template non è stato aggiornato

Controlla:

Automatically Apply Result

Se l’opzione è impostata su No, apri l’attività e fai clic su:

Apply Result

La correzione successiva non considera il risultato precedente

Controlla se il risultato precedente è stato applicato tramite:

Apply Result

La generazione successiva si basa sul template Magento attualmente salvato. Se il risultato del job ha stato completed, ma non è stato applicato, il job successivo continuerà a basarsi sulla versione precedente del template.

La risposta AI è stata rifiutata

Il modulo valida il JSON restituito. Può rifiutare il risultato se:

• mancano campi richiesti,
• i campi richiesti hanno tipi non corretti,
• nome del template, subject o content sono vuoti,
• content contiene il tag script,
• il risultato non è un JSON valido.

Controlla il messaggio di errore nell’attività e ripeti la generazione con un prompt più chiaro.

10. Impostazioni di produzione consigliate

Valori iniziali consigliati:

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

Usa l’applicazione manuale del risultato finché il team non sarà certo che i prompt, il modello selezionato e le regole di validazione producano template coerenti.