Instrucciones de instalación y configuración

1. Requisitos

El módulo está destinado a Magento 2 y a instalaciones gestionadas mediante Composer.

Requisitos:

• proyecto Magento 2 gestionado mediante Composer,
• versión de PHP compatible con la instalación de Magento utilizada,
• acceso a Magento CLI,
• OpenAI API key,
• proceso Magento Message Queue consumer en funcionamiento.

Paquete del módulo:

kowal/module-ai-email-theme-generator

Nombre del módulo Magento:

Kowal_AiEmailThemeGenerator

2. Instalación

Añade el repositorio Composer:

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

Si el repositorio es privado, configura la autenticación de GitHub:

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

Instala el módulo:

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

Activa el módulo:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Ejecuta la actualización de Magento:

bin/magento setup:upgrade

Limpia la caché:

bin/magento cache:flush

Para el modo de producción, ejecuta los comandos de despliegue estándar utilizados en el proyecto, por ejemplo:

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

3. Queue Consumer

La generación con IA se procesa de forma asíncrona mediante Magento Message Queue.

Ejecuta el consumer manualmente:

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

En entornos de producción, configura el consumer con supervisor, systemd u otro gestor de procesos utilizado por el hosting.

El módulo crea tareas en el panel de administración, pero la solicitud a la IA no se procesará hasta que el consumer esté en ejecución.

4. Permisos de administrador

El módulo añade recursos ACL:

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

Para que un administrador pueda usar el módulo, asigna los recursos correspondientes en:

System > Permissions > User Roles

Para acceso completo, permite el recurso principal AI Email Generation y todos los recursos secundarios.

5. Ubicación de la configuración

Ve a:

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

La sección de configuración contiene el grupo:

General Settings

6. Campos de configuración

Enabled

Tipo: Yes/No

Predeterminado: No

Activa o desactiva las funciones del módulo.

Cuando está configurado como No:

• el módulo no debería crear tareas de generación con IA,
• la acción de generación queda bloqueada,
• el administrador debe configurar primero el módulo.

Configura Yes solo después de preparar la API key y ejecutar el queue consumer.

API Provider

Tipo: Select

Predeterminado: OpenAI

Define el proveedor de IA utilizado por el módulo.

La implementación actual admite:

OpenAI

El campo existe para que en el futuro se puedan añadir otros providers sin cambiar el workflow del administrador.

OpenAI API Key

Tipo: campo oculto/cifrado

Almacena la OpenAI API key utilizada para la generación.

El valor es cifrado por Magento mediante:

MagentoConfigModelConfigBackendEncrypted

Importante:

• no incluyas la API key directamente en el código,
• no hagas commit de claves de entorno,
• limita el acceso a este campo mediante ACL,
• utiliza una clave con permisos adecuados para el proyecto.

OpenAI Model

Tipo: Select

Define el modelo OpenAI utilizado para la generación.

Ejemplo:

gpt-4.1

La lista se obtiene dinámicamente desde OpenAI Models API utilizando la API key configurada. El módulo filtra la respuesta a identificadores de modelos GPT y almacena la lista en caché durante un breve periodo para no llamar a la API cada vez que se abre la configuración.

Si la API key aún no se ha guardado, el campo mostrará una opción de reserva y pedirá al administrador que guarde la clave.

Si OpenAI API no está disponible temporalmente, el campo conserva el modelo configurado actualmente, siempre que sea posible.

Utiliza un modelo que admita el tipo de datos de entrada necesario:

• generación de texto para prompts y contenido de plantilla,
• modelo compatible con imágenes si se utilizan diseños gráficos de referencia.

El modelo seleccionado influye en la calidad del resultado, el tiempo de respuesta y el coste.

Request Timeout

Tipo: Number

Ejemplo de valor predeterminado:

120

Tiempo máximo en segundos permitido para una solicitud a OpenAI API.

Valores recomendados:

• 60 para generación de texto corta,
• 120 o más para generación compleja de HTML/CSS,
• valores más altos solo si la infraestructura permite tareas en cola de mayor duración.

El timeout se aplica al procesamiento en segundo plano, no a la solicitud del formulario de administración.

Maximum Retries

Tipo: Number

Ejemplo de valor predeterminado:

2

Define cuántas veces puede el consumer reintentar automáticamente una tarea de generación fallida.

Los reintentos son útiles ante errores temporales, como:

• timeout de API,
• error temporal del provider,
• rate limit,
• problema de red.

Los errores persistentes, por ejemplo una configuración incorrecta o una respuesta de IA no válida, deben revisarse en los detalles de la tarea.

Technical Prompt

Tipo: Textarea

Este prompt se aplica a cada solicitud de generación. Debe contener reglas técnicas que siempre deben respetarse.

Ejemplo:

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.

Utiliza este campo para instrucciones estables, como:

• conservar las directivas de Magento,
• mantener las variables obligatorias,
• evitar JavaScript,
• devolver únicamente JSON,
• escribir HTML compatible con clientes de correo,
• usar CSS en el campo de resultado correspondiente.

No utilices este campo para instrucciones creativas puntuales. Para eso sirve AI Prompt en el formulario de la plantilla.

Default User Prompt

Tipo: Textarea

Este prompt se muestra por defecto en la sección de IA del editor de plantillas de email.

Ejemplo:

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

El administrador puede modificarlo antes de crear la tarea de generación.

Utiliza este campo para establecer una instrucción predeterminada práctica para tareas de generación habituales.

Allowed Design File Types

Tipo: Text

Ejemplo de valor predeterminado:

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

Lista de extensiones de archivo permitidas para el diseño de referencia opcional, separadas por comas.

Ejemplos admitidos:

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

En producción, utiliza una lista lo más restrictiva posible. No permitas tipos de archivo que no sean necesarios en el proceso.

Maximum Design File Size

Tipo: Number

Ejemplo de valor predeterminado:

5242880

Tamaño máximo del archivo de referencia en bytes.

Ejemplos:

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

Los archivos grandes aumentan el tamaño del payload y pueden ralentizar la generación o superar los límites del provider.

Automatically Apply Result

Tipo: Yes/No

Predeterminado: No

Define si un resultado correcto de la IA debe sobrescribir inmediatamente los campos nativos de la plantilla de Magento.

Cuando está configurado como Yes, el consumer guarda el resultado generado en:

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

Cuando está configurado como No, el resultado se almacena en la tarea y el administrador puede revisarlo antes de aplicarlo manualmente.

Configuración recomendada para producción:

No

La aceptación manual es más segura, porque el resultado de la IA puede ser técnicamente correcto, pero aun así requerir revisión de marca, legal o de layout.

Keep Request and Response Payloads

Tipo: Yes/No

Predeterminado: Yes

Define si el módulo guarda los payloads completos de solicitud y respuesta en el registro de la tarea.

Cuando la opción está activada, los detalles de la tarea pueden mostrar:

• snapshot de la plantilla enviada a la IA,
• variables disponibles,
• prompts,
• metadatos del diseño de referencia,
• respuesta de la IA.

Esto resulta útil para depuración y auditoría.

En entornos de producción, revisa los requisitos de privacidad antes de activar esta opción. El módulo no debería enviar datos reales de clientes a la IA, pero los payloads pueden contener contenido de plantillas sensible desde el punto de vista empresarial.

Retention Days

Tipo: Number

Ejemplo de valor predeterminado:

30

Define durante cuánto tiempo deben conservarse las tareas antiguas.

Este valor documenta la política de retención prevista. El proyecto puede utilizarlo para implementar una limpieza periódica conforme a los requisitos operativos.

7. Ejemplo: generar la plantilla New Order Confirmation for Guest

Este ejemplo describe el proceso completo para generar una plantilla de email de Magento mejorada para:

New Order Confirmation for Guest

Paso 1: Configura el módulo

Ve a:

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

Configura:

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

Guarda la configuración y limpia la caché si Magento lo solicita.

Paso 2: Ejecuta el queue consumer

Ejecuta:

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

Durante las pruebas, el proceso debe estar en ejecución todo el tiempo.

Paso 3: Crea una plantilla nativa de Magento

Ve a:

Marketing > Communications > Email Templates

Haz clic en:

Add New Template

En el campo Template, selecciona:

New Order Confirmation for Guest

Haz clic en:

Load Template

Magento rellenará los campos nativos:

• Template Subject
• Template Content
• Template Styles

Define el nombre de la plantilla, por ejemplo:

New Order Confirmation for Guest - AI Draft

Guarda la plantilla.

El proceso de generación con IA requiere una plantilla guardada, porque la tarea debe tener un template_id persistente.

Paso 4: Completa AI Prompt

Después de guardar, vuelve a abrir la plantilla si es necesario. El editor estándar de plantillas de email de Magento contiene la sección AI Email Generation.

En el campo AI Prompt, introduce la instrucción de negocio, por ejemplo:

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.

Significado de este campo:

• describe el efecto de negocio esperado,
• se aplica solo a una tarea de generación concreta,
• puede contener instrucciones sobre marca, tono de comunicación, layout o contenido,
• no debe contener datos de API ni datos reales de clientes.

Paso 5: Añade opcionalmente Design Reference

Utiliza Design Reference si el email generado debe seguir una dirección visual concreta.

Archivos de ejemplo:

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

Significado de este campo:

• ofrece a la IA contexto visual o estructural adicional,
• ayuda a adaptar la plantilla al diseño gráfico,
• es opcional,
• debe cumplir los límites de extensiones y tamaño de archivos.

Si no se añade un diseño de referencia, la IA utilizará únicamente el contenido de la plantilla, las variables, el prompt técnico y el prompt de usuario.

Paso 6: Añade opcionalmente Error Screenshot

Utiliza Error Screenshot si quieres mostrar a la IA el problema actual de renderizado, layout o validación de la plantilla.

Ejemplos:

• captura de pantalla de una cabecera mal alineada,
• screenshot de un problema con el banner,
• vista previa del email con un espaciado incorrecto,
• captura de un cliente de correo que muestra un problema de responsividad,
• screenshot de un mensaje de error de una herramienta de pruebas.

Este campo se envía a la IA como una sección JSON independiente:

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

Significado de este campo:

• muestra a la IA el error actual que debe corregirse,
• no es un diseño gráfico ni un modelo del aspecto objetivo,
• ayuda a la IA a entender qué no funciona actualmente,
• debe utilizarse junto con una descripción clara del problema en AI Prompt.

Ejemplo 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.

Paso 7: Añade AI Assets estructurados

El editor contiene el área AI Assets. Estos recursos se guardan con la plantilla de Magento y se envían a la IA como URL de medios frontend agrupadas.

Grupos de recursos disponibles:

Cada recurso puede incluir:

Para banners e iconos, haz clic en:

Add BannerAdd Icon

El módulo guarda los recursos subidos en Magento media storage y envía a la IA URL públicas de frontend con la estructura:

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

En los prompts, haz referencia explícita a estos grupos. Ejemplo:

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.

Paso 8: Selecciona la generación después de guardar

Activa:

Generate with AI after saving

Significado de este campo:

• Magento primero guarda la plantilla con la acción save nativa estándar,
• tras un guardado correcto, el módulo crea una tarea de generación con IA,
• el diseño de referencia subido se adjunta a la tarea,
• la tarea se procesa de forma asíncrona mediante el queue consumer.

Si el checkbox no está marcado, el guardado de la plantilla funciona exactamente como el guardado estándar de Magento y no se crea ninguna tarea de IA.

Paso 9: Guarda la plantilla

Haz clic en el botón estándar de Magento:

Save Template

Después de guardar la plantilla, el módulo crea una tarea de generación.

En este momento:

• el guardado nativo de la plantilla ha finalizado,
• el estado de la tarea empieza en pending,
• el queue consumer procesa la tarea en segundo plano.

Paso 10: Revisa la tarea

Ve a:

Marketing > Communications > AI Email Generation Jobs

Abre la tarea creada.

Campos principales:

Estados habituales:

Paso 11: Aplica el resultado

Si Automatically Apply Result = No, el resultado no se guarda automáticamente en la plantilla de Magento.

Revisa:

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

Si el resultado es correcto, haz clic en:

Apply Result

El módulo guardará los valores generados en los campos nativos de la plantilla de Magento.

Paso 12: Verifica la plantilla de email nativa

Vuelve a:

Marketing > Communications > Email Templates

Abre la plantilla y comprueba:

• Template Name se ha actualizado,
• Template Subject se ha actualizado,
• Template Content contiene el HTML esperado y las directivas de Magento,
• Template Styles contiene el CSS esperado,
• las variables obligatorias de Magento no se han eliminado.

Envía un mensaje de prueba o ejecuta un flujo de pedido de prueba conforme al proceso QA estándar del proyecto.

Paso 13: Envía otra corrección a la IA

Después de aplicar el resultado mediante Apply Result, la versión actual de la plantilla queda guardada en los campos nativos de Magento. Esto significa que la siguiente solicitud de IA se basará en esa versión, no en la plantilla original.

Puedes perfeccionar la misma plantilla varias veces:

1. Aplica el resultado de la IA mediante Apply Result.
2. Vuelve a abrir la plantilla en Marketing > Communications > Email Templates.
3. Introduce un nuevo prompt que describa una corrección concreta.
4. Si el problema es visual, añade Error Screenshot.
5. Marca Generate with AI after saving.
6. Guarda la plantilla.
7. Revisa la nueva tarea y aplica el resultado si es correcto.

En las siguientes correcciones, trata AI Prompt como una descripción del cambio aplicado a la versión actual. Lo mejor es indicar:

• qué es incorrecto actualmente,
• qué resultado se debe conseguir,
• qué elementos no debería modificar la IA,
• si el Error Screenshot adjunto muestra un error de renderizado, layout visual, problema de responsividad o mensaje de validación.

Ejemplo de prompt para otra corrección:

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.

Este workflow es útil cuando la primera versión está cerca del resultado esperado, pero requiere ajustar detalles como espaciados, responsividad, visibilidad de banners, posición del logo o estilo de botones.

Puedes repetir este ciclo muchas veces. Cada nueva tarea crea una entrada independiente en el historial, por lo que se puede volver a prompts, payloads y respuestas de IA anteriores para comprobar qué instrucción provocó un cambio concreto.

8. Significado de los campos del payload de IA

El módulo envía a la IA un payload estructurado. Las secciones más importantes son:

template

Contiene el estado actual de la plantilla de Magento:

• ID de la plantilla,
• nombre de la plantilla,
• subject,
• content,
• styles,
• código original de la plantilla.

La IA utiliza esta sección como material base para la generación.

Importante: si previamente se aplicó el resultado de la IA mediante Apply Result, la sección template ya contiene esa versión actualizada. Gracias a ello, la siguiente generación puede funcionar como una corrección de la plantilla actual.

variables

Contiene variables y directivas de Magento detectadas en la plantilla.

La IA debe conservar estos valores y no debe inventar variables no compatibles.

prompts

Contiene:

• technical - prompt técnico global de la configuración,
• user - prompt introducido en el editor de la plantilla.

El prompt técnico protege la estructura específica de Magento. El prompt de usuario describe el resultado esperado para una sola plantilla.

design_reference

Contiene metadatos y contenido opcionales del diseño de referencia subido.

La sección está vacía cuando no se ha subido ningún archivo de referencia.

error_screenshot

Contiene un screenshot opcional que muestra errores actuales de renderizado, layout, visuales o de validación.

Esta sección tiene una descripción purpose y description para que la IA sepa que el archivo sirve para entender el problema, no como modelo del diseño objetivo.

La sección está vacía cuando no se ha subido ninguna captura de pantalla.

En correcciones posteriores conviene usar error_screenshot junto con un prompt preciso que indique qué debe corregirse y qué no debe cambiarse. Gracias a ello, la IA puede solucionar un problema concreto sin reconstruir toda la plantilla.

Ejemplo: después de aplicar el primer resultado de IA, el administrador observa que en Gmail el banner se superpone a la sección de resumen del pedido. En la siguiente solicitud, adjunta un screenshot de esa vista e introduce un prompt que pide únicamente corregir los espaciados y el ancho del banner. El payload sigue incluyendo el Template Content y Template Styles actuales, por lo que la IA trabaja sobre la última versión guardada.

assets

Contiene recursos gráficos estructurados guardados para la plantilla:

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

Cada recurso incluye la URL pública de medios, label, alt text, target URL, sort order y filename.

La IA debe usar estas URL al construir el HTML y no debe inventar direcciones de imágenes adicionales.

store_context

Contiene información básica sobre la tienda, como:

• store ID,
• locale,
• base URL.

La IA puede usarla para comprender el idioma y el contexto, pero no debe recibir datos reales de clientes ni pedidos.

9. Resolución de problemas

La tarea permanece en estado pending

Causa más probable:

• el queue consumer no está en ejecución.

Comprueba:

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

La página de configuración muestra access denied

Comprueba los permisos ACL para:

Kowal_AiEmailThemeGenerator::settings

Después de cambiar los permisos del administrador, cierra sesión y vuelve a iniciarla.

La generación termina con un error de falta de API key

Comprueba:

OpenAI API Key

Asegúrate de que el módulo está activado y de que la configuración se ha guardado en el scope correcto.

El resultado de IA tiene estado completed, pero la plantilla no se ha actualizado

Comprueba:

Automatically Apply Result

Si la opción está configurada como No, abre la tarea y haz clic en:

Apply Result

La siguiente corrección no tiene en cuenta el resultado anterior

Comprueba si el resultado anterior se aplicó mediante:

Apply Result

La siguiente generación se basa en la plantilla de Magento guardada actualmente. Si el resultado del job tiene estado completed, pero no se ha aplicado, el siguiente job seguirá basándose en la versión anterior de la plantilla.

La respuesta de la IA ha sido rechazada

El módulo valida el JSON devuelto. Puede rechazar el resultado si:

• faltan campos obligatorios,
• los campos obligatorios tienen tipos incorrectos,
• el nombre de la plantilla, subject o content están vacíos,
• content contiene la etiqueta script,
• el resultado no es un JSON válido.

Revisa el mensaje de error en la tarea y repite la generación con un prompt más claro.

10. Configuración recomendada para producción

Valores iniciales recomendados:

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

Utiliza la aplicación manual del resultado hasta que el equipo tenga la certeza de que los prompts, el modelo seleccionado y las reglas de validación generan plantillas coherentes.