Advanced Newsletter Suite para Magento 2 - guía de instalación y configuración

Objetivo del documento

Este documento describe la instalación y configuración del paquete magento-2-package-advanced-newsletter-suite. Es un paquete completo de newsletter y email marketing para Magento 2, que incluye audiencia, capture, campañas, contenido, envío, tracking, panel operativo y puntos de suscripción en frontend.

Requisitos previos

Antes de la implementación, prepara:

• Magento Open Source 2.4.x,
• Composer,
• acceso CLI a bin/magento,
• cuenta de administrador de Magento,
• credenciales de acceso a SMTP,
• cron de Magento configurado,
• disponibilidad para ejecutar consumidores de cola,
• un entorno de pruebas para verificar suscripciones, campañas y envíos.

Qué instala el paquete

El paquete incluye:

• Kowal_MarketingCore,
• Kowal_EmailTransport,
• Kowal_EmailSmtp,
• Kowal_EmailEvents,
• Kowal_EmailTemplateStudio,
• Kowal_NewsletterAudience,
• Kowal_NewsletterCapture,
• Kowal_NewsletterCampaigns,
• Kowal_NewsletterConsole,
• Kowal_NewsletterFrontend.

Es el nivel más alto de agregación dentro del ecosistema de módulos de email marketing para Magento.

Instalación

1. Instalación del paquete Composer

composer config repositories.kowal.package.advanced.newsletter.suite vcs https://github.com/kowalco/package-advanced-newsletter-suitecomposer config repositories.kowal.module.email.events vcs https://github.com/kowalco/module-email-eventscomposer config repositories.kowal.module.email.smtp vcs https://github.com/kowalco/module-email-smtpcomposer config repositories.kowal.module.email.template.studio vcs https://github.com/kowalco/module-email-template-studiocomposer config repositories.kowal.module.email.transport vcs https://github.com/kowalco/module-email-transportcomposer config repositories.kowal.module.marketing.core vcs https://github.com/kowalco/module-marketing-corecomposer config repositories.kowal.module.newsletter.audience vcs https://github.com/kowalco/module-newsletter-audiencecomposer config repositories.kowal.module.newsletter.campaigns vcs https://github.com/kowalco/module-newsletter-campaignscomposer config repositories.kowal.module.newsletter.capture vcs https://github.com/kowalco/module-newsletter-capturecomposer config repositories.kowal.module.newsletter.console vcs https://github.com/kowalco/module-newsletter-consolecomposer config repositories.kowal.module.newsletter.frontend vcs https://github.com/kowalco/module-newsletter-frontendcomposer config --global --auth github-oauth.github.com composer require kowal/package-advanced-newsletter-suite

2. Activación de módulos en Magento

bin/magento module:enable \ Kowal_MarketingCore \ Kowal_EmailTransport \ Kowal_EmailSmtp \ Kowal_EmailEvents \ Kowal_EmailTemplateStudio \ Kowal_NewsletterAudience \ Kowal_NewsletterCapture \ Kowal_NewsletterCampaigns \ Kowal_NewsletterConsole \ Kowal_NewsletterFrontendbin/magento setup:upgradebin/magento cache:flush

En modo producción, ejecuta además:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -f

Configuración

1. Sección administrativa

La configuración básica debería estar disponible en:

Kowal / Email Marketing

Según la especificación, los grupos de configuración esperados son:

• general,
• transport,
• smtp,
• campaigns,
• double_opt_in,
• events.

2. Configuración del envío

Primero configura la base del delivery:

• actividad del módulo,
• tipo de transporte por defecto,
• registro de envíos,
• cuenta o cuentas SMTP,
• routing de mensajes,
• fallback para cuentas de respaldo, si se utiliza.

La implementación del paquete completo sigue requiriendo una capa SMTP y de transporte plenamente funcional.

3. Configuración de audiencia y suscripciones

A continuación, confirma la configuración de la capa de audiencia:

• integración con newsletter_subscriber,
• listas de correo,
• segmentos,
• estados de suscripción,
• metadatos adicionales del suscriptor,
• fuentes de captación,
• consentimientos de marketing.

Configura también el proceso de suscripción:

• formularios y puntos de suscripción,
• double opt-in,
• plantilla del mensaje de confirmación,
• tiempo de validez del token de confirmación.

4. Configuración de campañas

En la sección campaigns configura:

• batch_size,
• max_retry_count,
• send_rate_limit_per_run,
• watchdog_timeout_minutes.

El paquete admite:

• definición de campañas,
• calendario,
• cola de destinatarios,
• procesamiento por lotes del envío,
• historial de ejecución de campañas,
• envíos de prueba.

5. Configuración de Template Studio

Si la implementación incluye trabajo con contenido de newsletter, configura EmailTemplateStudio según el alcance del MVP:

• trabajo con plantillas nativas de newsletter de Magento,
• selección de layouts de producto,
• guardado de la sección generada en la plantilla nativa,
• importación del contenido listo a la campaña.

6. Configuración de eventos de email

En la sección events configura:

• procesamiento de eventos,
• retención de payloads,
• política de aceptación de eventos duplicados de proveedores.

La capa EmailEvents se encarga de la observabilidad del proceso de entrega y de vincular los eventos con los logs de transporte y las campañas.

7. Configuración del panel administrativo y del frontend

El paquete completo incluye:

• Kowal_NewsletterConsole como panel operativo,
• Kowal_NewsletterFrontend como capa de formularios y widgets de suscripción en frontend.

Tras la instalación, verifica:

• la disponibilidad del dashboard,
• los accesos directos a la configuración y a los módulos operativos,
• la vista de los últimos errores y envíos,
• la presencia de formularios de suscripción en el frontend de la tienda.

Cron y consumidores de cola

El paquete completo requiere procesamiento asíncrono en funcionamiento.

1. Cron de Magento

bin/magento cron:install

El cron debería encargarse de:

• planificación de campañas,
• recuperación de tareas,
• watchdog operativo.

2. Queue consumers

Los consumidores de cola deberían encargarse del procesamiento real de los lotes de envío. Los nombres de los consumidores deben obtenerse de los archivos actuales etc/queue_consumer.xml de los módulos implementados.

En un entorno de producción, asegúrate de contar con:

• ejecución de consumers en segundo plano,
• arranque automático tras reiniciar el servidor,
• monitorización de fallos,
• registro de errores.

Pasos después de la instalación

Tras la implementación, ejecuta la lista de comprobación completa:

1. Configura y prueba la cuenta SMTP.
2. Verifica el routing de mensajes.
3. Comprueba la suscripción del suscriptor y el double opt-in.
4. Confirma la compatibilidad con el newsletter nativo de Magento.
5. Crea una lista o segmento de prueba.
6. Prepara una campaña de prueba.
7. Realiza un test send.
8. Comprueba la planificación de campañas mediante cron.
9. Verifica el procesamiento de la cola mediante consumers.
10. Confirma el registro de logs y eventos de email.
11. Comprueba el dashboard administrativo.
12. Verifica los formularios y widgets de suscripción en frontend.

Prueba de aceptación tras la implementación

El paquete está correctamente implementado si:

• los módulos se instalan correctamente en Magento 2.4.x,
• el envío SMTP funciona a nivel de cuentas y routing,
• la suscripción del suscriptor sigue siendo compatible con el newsletter nativo de Magento,
• la campaña se planifica mediante cron y se procesa mediante queue consumer,
• los estados de entrega actualizan los logs y los eventos de email,
• el panel administrativo muestra los datos operativos básicos,
• los puntos de suscripción en frontend funcionan correctamente,
• tras desactivar los módulos, el mecanismo base Magento_Newsletter puede seguir funcionando.

Notas de implementación

• Conviene implementar el paquete completo junto con una configuración probada de SMTP y tracking.
• Los datos ampliados deben almacenarse en tablas propias, sin duplicar la tabla nativa newsletter_subscriber.
• La documentación operativa de la implementación debería incluir además el procedimiento de gestión de colas, webhooks y pruebas de regresión de la configuración administrativa.

Amazon SES - creación de cuenta y configuración para la integración de envíos

Objetivo del documento

Este documento describe cómo preparar una cuenta de AWS y el servicio Amazon SES para poder realizar la integración de envíos con los módulos de este proyecto.

La guía incluye:

• creación de una cuenta de AWS,
• activación de Amazon SES,
• verificación del dominio y del remitente,
• salida del sandbox,
• preparación de credenciales,
• dos variantes de integración con Magento:
  • mediante Amazon SES API,
  • mediante Amazon SES SMTP.

Nota importante para este proyecto

En el código del proyecto hay dos rutas de integración disponibles con Amazon SES:

1. SES API en Kowal_EmailTransport con el tipo de transporte ses.
2. SES SMTP en Kowal_EmailSmtp con el tipo de transporte smtp.

Esto significa que conviene preparar la cuenta de AWS y SES una sola vez, pero la forma final de conectarla con Magento depende de la variante de implementación elegida.

Supuestos previos

Antes de comenzar, prepara:

• el dominio desde el que se enviarán los mensajes, por ejemplo example.com,
• acceso al DNS de ese dominio,
• una dirección del remitente, por ejemplo newsletter@example.com,
• una tarjeta de pago o un método de facturación activo en AWS,
• la decisión sobre en qué región funcionará SES, por ejemplo eu-central-1 o us-east-1.

1. Creación de una cuenta de AWS

1. Entra en el panel de AWS: https://aws.amazon.com/
2. Crea una cuenta de AWS.
3. Activa MFA para la cuenta root.
4. No utilices las claves de acceso de la cuenta root para la integración de aplicaciones.

Para la integración con Magento, prepara un usuario IAM independiente o credenciales SMTP independientes, según la variante elegida.

2. Activación de Amazon SES

1. Inicia sesión en AWS Console.
2. Abre el servicio Amazon Simple Email Service.
3. Selecciona la región en la que quieres gestionar los envíos.

Esto es importante porque en SES la región tiene relevancia operativa:

• las identidades del remitente se mantienen por región,
• el estado sandbox/production access se aplica por región,
• los datos de configuración de Magento deben apuntar a esa misma región,
• las credenciales SMTP en SES son únicas por región.

Si la tienda opera a nivel internacional, lo mejor es definir desde el principio la región objetivo para ese mercado o para toda la organización y mantenerla de forma coherente.

3. Verificación del dominio o de la dirección del remitente

La mejor práctica para una tienda es verificar todo el dominio y no solo una única dirección de email.

Variante recomendada

Verifica el dominio, por ejemplo example.com.

Gracias a ello:

• puedes enviar desde varias direcciones de ese dominio,
• resulta más fácil pasar al envío en producción,
• te preparas mejor para campañas, transacciones y múltiples remitentes,
• es más fácil gestionar varias tiendas, idiomas y marcas dentro de un mismo ecosistema.

Pasos

1. En SES, ve a Identities.
2. Selecciona Create identity.
3. Selecciona el tipo Domain.
4. Introduce el dominio de envío.
5. Activa Easy DKIM si no tienes motivos para usar tus propias claves DKIM.
6. Añade a tu zona DNS los registros DNS indicados por AWS.
7. Espera a que el estado sea Verified.

Alcance mínimo de DNS

En la práctica, necesitarás al menos:

• registros de verificación de SES,
• registros DKIM,
• opcionalmente, un registro para custom MAIL FROM.

4. Salida del sandbox de SES

Una cuenta nueva de SES suele funcionar inicialmente en sandbox.

Esto significa, entre otras cosas, que:

• solo puedes enviar desde identidades verificadas,
• los destinatarios también deben estar verificados,
• no podrás realizar envíos normales de producción a clientes de la tienda.

Pasos

1. En SES, abre Account dashboard o la pantalla inicial de configuración.
2. Selecciona la opción Request production access.
3. Completa el formulario según el uso previsto del sistema:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Describe que el envío se realizará desde tu propio Magento para una tienda online.
5. Envía la solicitud.

Antes de enviar la solicitud, conviene tener ya el dominio verificado. Esto suele acelerar la aprobación.

5. Configuración de entregabilidad

No es el mínimo obligatorio para la primera prueba, pero sí es muy recomendable antes de producción.

DKIM

Si utilizas Easy DKIM, SES firma los mensajes automáticamente una vez que el DNS está configurado correctamente.

Custom MAIL FROM

Si quieres mejorar el control sobre el remitente técnico y la entregabilidad:

1. Abre el dominio verificado en SES.
2. Configura Custom MAIL FROM domain, por ejemplo mail.example.com.
3. Añade al DNS:
   • registro MX,
   • registro SPF/TXT para MAIL FROM.

Esto es especialmente recomendable para tiendas que realizan email marketing de forma habitual y quieren reducir problemas de reputación del remitente.

6. Variante A - integración mediante Amazon SES API

Esta variante utiliza el tipo de transporte ses disponible en Kowal_EmailTransport.

Cuándo elegir esta variante

Elige SES API si:

• quieres utilizar Amazon SES directamente como proveedor,
• quieres mantener una cuenta de transporte del tipo ses,
• quieres enrutar mensajes mediante Kowal_EmailTransport.

6.1. Creación de un usuario IAM para el envío

No utilices la cuenta root.

Prepara un usuario IAM independiente, por ejemplo:

• magento-ses-sender

A continuación, asígnale una política con permisos mínimos para el envío.

Ejemplo de política mínima

{ 'Version': '2012-10-17', 'Statement': [ { 'Effect': 'Allow', 'Action': [ 'ses:SendEmail', 'ses:SendRawEmail' ], 'Resource': '*' } ]}

Si quieres, puedes ampliarla con lectura de límites o estadísticas, pero para el propio envío este alcance es un punto de partida suficiente.

6.2. Creación de Access Key y Secret Key

1. Abre IAM.
2. Ve a Users.
3. Abre el usuario preparado.
4. Entra en la pestaña Security credentials.
5. En la sección Access keys selecciona Create access key.
6. Guarda:
   • Access Key ID
   • Secret Access Key

Solo verás el secreto una vez. Si lo pierdes, tendrás que crear una nueva clave.

6.3. Datos necesarios en Magento para la variante API

Para la cuenta de transporte ses en Magento, prepara:

• provider_region, por ejemplo eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email opcionalmente,
• store_id, si la cuenta debe funcionar solo para una store view concreta.

6.4. Correspondencia con el panel de Magento

En Kowal / Email Marketing:

1. Añade una nueva cuenta de transporte.
2. Configura:
   • Transport Type = Amazon SES,
   • Region = región de SES,
   • Access Key = clave IAM,
   • Secret Key = secreto IAM.
3. Guarda la cuenta.
4. Asocia la cuenta al routing de mensajes.
5. Realiza una prueba de envío desde la cuenta de transporte.

7. Variante B - integración mediante Amazon SES SMTP

Esta variante utiliza Kowal_EmailSmtp.

Cuándo elegir esta variante

Elige SES SMTP si:

• quieres implementar Amazon SES como fuente SMTP,
• utilizas el paquete Advance Email Delivery,
• quieres mantener un modelo de integración más simple en Magento.

7.1. Creación de credenciales SMTP en SES

1. Abre Amazon SES.
2. Ve a SMTP settings.
3. Selecciona Create SMTP credentials.
4. AWS te guiará en la creación de un usuario IAM para SMTP.
5. Guarda:
   • SMTP username
   • SMTP password

Estas no son claves AWS normales. Son credenciales SMTP independientes para SES.

7.2. Endpoint SMTP

Para SES, utiliza un host con el formato:

email-smtp..amazonaws.com

Ejemplo:

email-smtp.eu-central-1.amazonaws.com

7.3. Puerto y cifrado

Configuraciones más habituales:

• puerto 587 + STARTTLS,
• o puerto 465 + TLS Wrapper / SSL.

En la práctica, para Magento el punto de partida más seguro es:

• host: email-smtp..amazonaws.com
• port: 587
• security: STARTTLS

7.4. Datos necesarios en Magento para la variante SMTP

Prepara:

• host SMTP,
• puerto,
• tipo de cifrado,
• login SMTP,
• contraseña SMTP,
• dirección del remitente compatible con la verified identity en SES.

7.5. Correspondencia con el panel de Magento

En Kowal / Email Marketing:

1. En la sección smtp configura globalmente:
   • enabled = Yes,
   • host = endpoint de SES,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = dirección para prueba.
2. Guarda la configuración.
3. Ejecuta Send Test Email.

Si utilizas varias cuentas o varias store view, también puedes configurar una cuenta de transporte independiente del tipo smtp con datos de conexión dedicados.

8. Qué elegir en este proyecto

Elige SES API si:

• quieres usar cuentas de transporte ses,
• quieres enrutar envíos por cuenta y proveedor,
• quieres desarrollar el transporte sin basarlo todo en la capa SMTP.

Elige SES SMTP si:

• te interesa una primera implementación más rápida,
• quieres tratar SES como un servidor SMTP externo,
• implementas principalmente el paquete delivery basado en Kowal_EmailSmtp.

9. Checklist mínima antes de la prueba de envío

Antes de la primera prueba, confirma:

1. La cuenta de AWS existe y tiene facturación activa.
2. La región de SES ha sido seleccionada.
3. El dominio o la dirección del remitente tienen estado Verified.
4. La cuenta de SES tiene production access o solo estás probando en condiciones de sandbox.
5. DKIM está configurado.
6. Magento tiene los datos del remitente correctos.
7. Se ha elegido la variante de integración:
   • API,
   • o SMTP.
8. Las credenciales se han guardado de forma segura.
9. Se ha enviado una prueba y se ha confirmado la entrega del mensaje.

10. Errores más habituales

La cuenta sigue en sandbox

Síntoma:

• el mensaje no se envía a destinatarios normales.

Causa:

• falta de production access.

El dominio no está verificado

Síntoma:

• error del remitente o rechazo del envío.

Causa:

• falta de verified identity para el dominio o la dirección del remitente.

Región incorrecta

Síntoma:

• los datos parecen correctos, pero el envío sigue sin funcionar.

Causa:

• la identidad está verificada en una región distinta de la utilizada por la integración.

Confusión entre claves API y credenciales SMTP

Síntoma:

• el inicio de sesión SMTP no funciona.

Causa:

• se introdujeron claves IAM en SMTP en lugar de SMTP username y SMTP password.

Uso de la cuenta root

Síntoma:

• falta de separación de seguridad y rotación de credenciales más difícil.

Causa:

• integración basada en datos root en lugar de un usuario IAM independiente o credenciales SMTP independientes.

11. Enlaces a la documentación oficial de AWS

• Set up your SES account: https://docs.aws.amazon.com/ses/latest/dg/setting-up.html
• Creating and verifying identities: https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html
• Verified identities: https://docs.aws.amazon.com/ses/latest/dg/verify-addresses-and-domains.html
• Request production access: https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html
• SMTP credentials: https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html
• SMTP endpoint connection: https://docs.aws.amazon.com/ses/latest/dg/smtp-connect.html
• Custom MAIL FROM: https://docs.aws.amazon.com/ses/latest/dg/mail-from.html
• SES regions: https://docs.aws.amazon.com/ses/latest/dg/regions.html
• SES credentials overview: https://docs.aws.amazon.com/ses/latest/dg/send-email-concepts-credentials.html
• IAM access keys: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

12. Datos que deben entregarse para la implementación

Al final, la persona que configure SES debe proporcionar para la implementación exactamente este conjunto:

Para la variante SES API

• región de SES,
• verified domain,
• access key,
• secret key,
• dirección del remitente,
• reply-to, si debe ser diferente,
• información sobre si la cuenta debe funcionar globalmente o por store view.

Para la variante SES SMTP

• región de SES,
• host SMTP,
• puerto,
• security mode,
• SMTP username,
• SMTP password,
• dirección del remitente,
• dirección de prueba para verificación.