Advanced Newsletter Suite para Magento 2 - instruções de instalação e configuração

Objetivo do documento

Este documento descreve a instalação e configuração do pacote magento-2-package-advanced-newsletter-suite. Trata-se de um pacote completo de newsletter e email marketing para Magento 2, abrangendo destinatários, capture, campanhas, conteúdo, envio, tracking, painel operacional e pontos de subscrição no frontend.

Requisitos prévios

Antes da implementação, prepare:

• Magento Open Source 2.4.x,
• Composer,
• acesso CLI a bin/magento,
• conta de administrador Magento,
• credenciais de acesso SMTP,
• cron do Magento configurado,
• disponibilidade para executar consumidores de filas,
• ambiente de teste para verificar subscrição, campanhas e envios.

O que o pacote instala

O pacote inclui:

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

Este é o mais alto nível de agregação no ecossistema de módulos de email marketing para Magento.

Instalação

1. Instalação do pacote 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. Ativação dos módulos no 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

No modo de produção, execute adicionalmente:

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

Configuração

1. Secção administrativa

A configuração base deverá estar disponível em:

Kowal / Email Marketing

De acordo com a especificação, os grupos de definições esperados são:

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

2. Configuração de envio

Comece por configurar a base de delivery:

• atividade do módulo,
• tipo de transporte predefinido,
• registo dos envios,
• conta ou contas SMTP,
• routing de mensagens,
• fallback para contas de reserva, se utilizado.

A implementação do pacote completo continua a exigir uma camada SMTP e de transporte funcional.

3. Configuração de destinatários e subscrições

Em seguida, confirme a configuração da camada de destinatários:

• integração com newsletter_subscriber,
• listas de mailing,
• segmentos,
• estados de subscrição,
• metadados adicionais do subscritor,
• fontes de aquisição,
• consentimentos de marketing.

Configure também o processo de subscrição:

• formulários e pontos de subscrição,
• double opt-in,
• template da mensagem de confirmação,
• tempo de validade do token de confirmação.

4. Configuração de campanhas

Na secção campaigns defina:

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

O pacote suporta:

• definição de campanhas,
• agenda,
• fila de destinatários,
• batch processing de envio,
• histórico de execução de campanhas,
• envios de teste.

5. Configuração do Template Studio

Se a implementação abranger trabalho com conteúdo de newsletter, configure o EmailTemplateStudio de acordo com o âmbito MVP:

• trabalho com templates nativos de newsletter do Magento,
• seleção de layouts de produto,
• gravação da secção gerada no template nativo,
• importação do conteúdo final para a campanha.

6. Configuração de eventos de email

Na secção events configure:

• processamento de eventos,
• retenção de payloads,
• política de aceitação de duplicados de eventos provenientes de fornecedores.

A camada EmailEvents é responsável pela observabilidade do processo de entrega e pela ligação dos eventos aos logs de transporte e às campanhas.

7. Configuração do painel administrativo e do frontend

O pacote completo inclui:

• Kowal_NewsletterConsole como painel operacional,
• Kowal_NewsletterFrontend como camada de formulários e widgets de subscrição no frontend.

Após a instalação, verifique:

• disponibilidade do dashboard,
• atalhos para configuração e módulos operacionais,
• vista dos últimos erros e envios,
• presença de formulários de subscrição no frontend da loja.

Cron e consumidores de filas

O pacote completo requer processamento assíncrono em funcionamento.

1. Cron do Magento

bin/magento cron:install

O cron deverá ser responsável por:

• planeamento de campanhas,
• recuperação de tarefas,
• watchdog operacional.

2. Queue consumers

Os consumidores de filas deverão ser responsáveis pelo processamento efetivo dos batches de envio. Os nomes dos consumidores devem ser obtidos dos ficheiros atuais etc/queue_consumer.xml dos módulos implementados.

Em ambiente de produção, assegure:

• execução dos consumers em background,
• arranque automático após reinício do servidor,
• monitorização de falhas,
• registo de erros.

Passos após a instalação

Após a implementação, execute a checklist completa:

1. Configure e teste a conta SMTP.
2. Verifique o routing das mensagens.
3. Teste a subscrição do subscritor e o double opt-in.
4. Confirme a compatibilidade com a newsletter nativa do Magento.
5. Crie uma lista ou segmento de teste.
6. Prepare uma campanha de teste.
7. Execute um test send.
8. Verifique o planeamento de campanhas via cron.
9. Confirme o processamento da fila pelos consumers.
10. Confirme o registo de logs e eventos de email.
11. Verifique o dashboard administrativo.
12. Verifique os formulários e widgets de subscrição no frontend.

Teste de aceitação após a implementação

O pacote está corretamente implementado se:

• os módulos se instalarem corretamente no Magento 2.4.x,
• o envio SMTP funcionar a partir das contas e do routing,
• a subscrição do subscritor permanecer compatível com a newsletter nativa do Magento,
• a campanha for planeada pelo cron e processada pelo queue consumer,
• os estados de entrega atualizarem os logs e eventos de email,
• o painel administrativo apresentar os dados operacionais básicos,
• os pontos de subscrição no frontend funcionarem corretamente,
• após desativação dos módulos, o mecanismo base Magento_Newsletter continuar a poder funcionar.

Notas de implementação

• Vale a pena implementar o pacote completo juntamente com uma configuração SMTP e de tracking já validada.
• Os dados adicionais devem ser armazenados nas suas próprias tabelas, sem duplicar a tabela nativa newsletter_subscriber.
• A documentação operacional da implementação deverá incluir adicionalmente o procedimento de gestão de filas, webhooks e testes de regressão da configuração administrativa.

Amazon SES - criação de conta e configuração para integração de envio

Objetivo do documento

Este documento descreve como preparar a conta AWS e o serviço Amazon SES para que seja possível realizar a integração de envio com os módulos deste projeto.

As instruções incluem:

• criação de conta AWS,
• ativação do Amazon SES,
• verificação do domínio e do remetente,
• saída do sandbox,
• preparação das credenciais,
• duas variantes de integração com Magento:
  • através de Amazon SES API,
  • através de Amazon SES SMTP.

Nota importante para este projeto

No código do projeto existem dois caminhos de integração com o Amazon SES:

1. SES API em Kowal_EmailTransport com o tipo de transporte ses.
2. SES SMTP em Kowal_EmailSmtp com o tipo de transporte smtp.

Isto significa que vale a pena preparar a conta AWS e o SES uma única vez, mas a forma final de ligação ao Magento depende da variante de implementação escolhida.

Pressupostos iniciais

Antes de começar, prepare:

• o domínio a partir do qual serão enviadas as mensagens, por exemplo example.com,
• acesso ao DNS desse domínio,
• endereço do remetente, por exemplo newsletter@example.com,
• cartão bancário ou método de faturação ativo na AWS,
• decisão sobre a região em que o SES vai funcionar, por exemplo eu-central-1 ou us-east-1.

1. Criação da conta AWS

1. Aceda ao painel AWS: https://aws.amazon.com/
2. Crie uma conta AWS.
3. Ative MFA para a conta root.
4. Não utilize as chaves de acesso da conta root para integração da aplicação.

Para a integração com Magento, prepare um utilizador IAM separado ou credenciais SMTP separadas, consoante a variante escolhida.

2. Ativação do Amazon SES

1. Inicie sessão na AWS Console.
2. Abra o serviço Amazon Simple Email Service.
3. Selecione a região em que pretende operar o envio.

Isto é importante porque, no SES, a região tem importância operacional:

• as identidades do remetente são mantidas por região,
• o estado sandbox/production access aplica-se por região,
• os dados de configuração do Magento têm de apontar para a mesma região,
• as credenciais SMTP no SES são únicas por região.

Se a loja operar internacionalmente, o ideal é definir desde logo a região de destino para determinado mercado ou para toda a organização e mantê-la de forma consistente.

3. Verificação do domínio ou do endereço do remetente

A melhor prática para uma loja é verificar todo o domínio, e não apenas um endereço de email individual.

Variante recomendada

Verifique o domínio, por exemplo example.com.

Graças a isso:

• pode enviar a partir de vários endereços desse domínio,
• é mais fácil passar para envio em produção,
• fica melhor preparado para campanhas, transações e vários remetentes,
• torna-se mais fácil gerir várias lojas, idiomas e marcas num único ecossistema.

Passos

1. No SES, vá a Identities.
2. Selecione Create identity.
3. Escolha o tipo Domain.
4. Introduza o domínio de envio.
5. Ative Easy DKIM, se não tiver motivo para usar as suas próprias chaves DKIM.
6. Adicione os registos DNS indicados pela AWS à sua zona DNS.
7. Aguarde pelo estado Verified.

Âmbito mínimo de DNS

Na prática, vai precisar de pelo menos:

• registos de verificação SES,
• registos DKIM,
• opcionalmente um registo para custom MAIL FROM.

4. Saída do sandbox do SES

Uma nova conta SES funciona normalmente, numa fase inicial, em sandbox.

Isto significa, entre outras coisas, que:

• só pode enviar a partir de identidades verificadas,
• os destinatários também têm de estar verificados,
• não será possível realizar envio normal em produção para clientes da loja.

Passos

1. No SES, abra o Account dashboard ou o ecrã inicial de configuração.
2. Selecione a opção Request production access.
3. Preencha o formulário de acordo com a finalidade do sistema:
   • transactional,
   • marketing,
   • newsletter,
   • e-commerce communications.
4. Descreva que o envio será realizado a partir do seu próprio Magento para uma loja online.
5. Submeta o pedido.

Antes de submeter o pedido, é aconselhável ter já o domínio verificado. Isso normalmente acelera a aprovação.

5. Configuração da deliverability

Este não é o mínimo obrigatório para o primeiro teste, mas é fortemente recomendado antes da produção.

DKIM

Se utilizar Easy DKIM, o SES assina as mensagens automaticamente após a configuração correta do DNS.

Custom MAIL FROM

Se pretender melhorar o controlo sobre o remetente técnico e a deliverability:

1. Abra o domínio verificado no SES.
2. Configure Custom MAIL FROM domain, por exemplo mail.example.com.
3. Adicione ao DNS:
   • registo MX,
   • registo SPF/TXT para MAIL FROM.

Isto faz especialmente sentido para lojas que operam email marketing regular e pretendem reduzir problemas com a reputação do remetente.

6. Variante A - integração via Amazon SES API

Esta variante utiliza o tipo de transporte ses disponível em Kowal_EmailTransport.

Quando escolher esta variante

Escolha SES API se:

• pretende usar diretamente o Amazon SES como provider,
• pretende manter uma conta de transporte do tipo ses,
• pretende fazer routing das mensagens através de Kowal_EmailTransport.

6.1. Criação de utilizador IAM para envio

Não utilize a conta root.

Prepare um utilizador IAM separado, por exemplo:

• magento-ses-sender

Em seguida, atribua-lhe uma política com as permissões mínimas para envio.

Exemplo de política mínima

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

Se quiser, pode alargá-la com leitura de limites ou estatísticas, mas para o envio em si este âmbito é o ponto de partida.

6.2. Criação de Access Key e Secret Key

1. Abra IAM.
2. Vá a Users.
3. Abra o utilizador preparado.
4. Entre no separador Security credentials.
5. Na secção Access keys, selecione Create access key.
6. Guarde:
   • Access Key ID
   • Secret Access Key

O segredo só será mostrado uma vez. Se o perder, terá de criar uma nova chave.

6.3. Dados necessários no Magento para a variante API

Para a conta de transporte ses no Magento, prepare:

• provider_region, por exemplo eu-central-1,
• provider_api_key,
• provider_api_secret,
• sender_name,
• sender_email,
• reply_to_email opcionalmente,
• store_id, se a conta for funcionar apenas para uma store view específica.

6.4. Mapeamento para o painel Magento

Em Kowal / Email Marketing:

1. Adicione uma nova conta de transporte.
2. Defina:
   • Transport Type = Amazon SES,
   • Region = região SES,
   • Access Key = chave IAM,
   • Secret Key = segredo IAM.
3. Guarde a conta.
4. Associe a conta ao routing de mensagens.
5. Execute um teste de envio a partir da conta de transporte.

7. Variante B - integração via Amazon SES SMTP

Esta variante utiliza Kowal_EmailSmtp.

Quando escolher esta variante

Escolha SES SMTP se:

• pretende implementar o Amazon SES como fonte SMTP,
• utiliza o pacote Advance Email Delivery,
• pretende manter um modelo de integração mais simples do lado do Magento.

7.1. Criação de credenciais SMTP no SES

1. Abra Amazon SES.
2. Vá a SMTP settings.
3. Selecione Create SMTP credentials.
4. A AWS irá guiá-lo na criação de um utilizador IAM para SMTP.
5. Guarde:
   • SMTP username
   • SMTP password

Estas não são chaves AWS normais. São credenciais SMTP separadas para o SES.

7.2. Endpoint SMTP

Para o SES, utilize um host no formato:

email-smtp..amazonaws.com

Exemplo:

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

7.3. Porta e encriptação

As definições mais utilizadas são:

• porta 587 + STARTTLS,
• ou porta 465 + TLS Wrapper / SSL.

Na prática, para Magento, o ponto de partida mais seguro é:

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

7.4. Dados necessários no Magento para a variante SMTP

Prepare:

• host SMTP,
• porta,
• tipo de encriptação,
• login SMTP,
• palavra-passe SMTP,
• endereço do remetente compatível com a verified identity no SES.

7.5. Mapeamento para o painel Magento

Em Kowal / Email Marketing:

1. Na secção smtp, defina globalmente:
   • enabled = Yes,
   • host = endpoint SES,
   • port = 587,
   • username = SMTP username,
   • password = SMTP password,
   • connection_security = STARTTLS,
   • test_recipient_email = endereço para teste.
2. Guarde a configuração.
3. Execute Send Test Email.

Se utilizar várias contas ou várias store views, também pode configurar uma conta de transporte separada do tipo smtp com dados de ligação dedicados.

8. O que escolher neste projeto

Escolha SES API se:

• pretende usar contas de transporte ses,
• pretende fazer routing do envio por conta e provider,
• pretende desenvolver o transporte sem assentar tudo na camada SMTP.

Escolha SES SMTP se:

• pretende uma primeira implementação mais rápida,
• pretende tratar o SES como servidor SMTP externo,
• está a implementar sobretudo o pacote delivery baseado em Kowal_EmailSmtp.

9. Checklist mínima antes do teste de envio

Antes do primeiro teste, confirme:

1. A conta AWS existe e tem faturação ativa.
2. A região SES foi selecionada.
3. O domínio ou o endereço do remetente têm estado Verified.
4. A conta SES tem production access ou está a testar apenas em condições de sandbox.
5. O DKIM está configurado.
6. O Magento tem dados corretos do remetente.
7. A variante de integração foi escolhida:
   • API,
   • ou SMTP.
8. As credenciais estão guardadas em segurança.
9. Foi enviado um teste e confirmada a entrega da mensagem.

10. Erros mais frequentes

A conta ainda está em sandbox

Sintoma:

• a mensagem não é enviada para destinatários normais.

Causa:

• falta de production access.

O domínio não está verificado

Sintoma:

• erro de remetente ou rejeição do envio.

Causa:

• falta de verified identity para o domínio ou endereço do remetente.

Região errada

Sintoma:

• os dados parecem corretos, mas o envio continua sem funcionar.

Causa:

• a identidade está verificada numa região diferente daquela utilizada pela integração.

Confusão entre chaves API e credenciais SMTP

Sintoma:

• o login SMTP não funciona.

Causa:

• foram introduzidas no SMTP chaves IAM em vez de SMTP username e SMTP password.

Utilização da conta root

Sintoma:

• falta de separação de segurança e rotação mais difícil das credenciais.

Causa:

• integração baseada em dados root em vez de um utilizador IAM separado ou credenciais SMTP separadas.

11. Ligações para a documentação oficial 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. Dados que devem ser fornecidos para a implementação

No final, a pessoa que configura o SES deve fornecer para a implementação exatamente este conjunto:

Para a variante SES API

• região SES,
• verified domain,
• access key,
• secret key,
• endereço do remetente,
• reply-to, se tiver de ser diferente,
• informação sobre se a conta deve funcionar globalmente ou por store view.

Para a variante SES SMTP

• região SES,
• host SMTP,
• porta,
• security mode,
• SMTP username,
• SMTP password,
• endereço do remetente,
• endereço de teste para verificação.