# Amazon SES no Mautic 7 via mpm

Este guia leva de "tenho um Mautic 7 rodando" a "e-mail saindo pela Amazon SES com batch, rate limit e circuit breaker".

Todos os comandos abaixo foram executados de ponta a ponta numa instância real (Mautic 7.1.2, imagem oficial mautic/mautic:7-apache).

# Pré-requisitos

• Mautic 7.x rodando em container Docker
• mpm instalado no host (curl -sL https://mpm.mtc.codes/init.sh | sudo bash)
• API key do marketplace com contrato ativo para amazonses
• Conta AWS com SES em produção (fora do sandbox) e domínio verificado
• Um par de chaves IAM com permissão ses:SendEmail / ses:SendRawEmail

# 1. Descobrir onde ficam os plugins

Faça isso antes de qualquer coisa. A imagem oficial do Mautic 7 usa layout docroot — os plugins ficam em /var/www/html/docroot/plugins, não em /var/www/html/plugins. Instalações montadas de outro jeito podem divergir.

docker exec <container> find /var/www -maxdepth 3 -type d -name plugins

Se a resposta contiver docroot, você vai precisar do --plugins-dir no passo seguinte. Pular esta checagem é a causa nº 1 de "instalou mas não aparece no Mautic".

# 2. Registrar a instância no mpm

mpm instance add m7prod \
  --container mautic7_prod \
  --mautic-version 7 \
  --url https://mautic.seudominio.com.br \
  --plugins-dir /var/www/html/docroot/plugins \
  --console /var/www/html/bin/console

Confira:

mpm instance list

O --mautic-version precisa bater com a major real. Se errar, o plugin baixa mas o warmup falha (e o mpm faz rollback automático).

# 3. Instalar o plugin

mpm install amazonses --instance m7prod

O mpm roda um pipeline de 14 etapas: resolve, baixa da CDN, valida a estrutura, faz backup, instala no container, corrige permissões, limpa e reaquece o cache, roda migrações, recarrega os plugins e faz health check. Se qualquer etapa falhar, ele restaura o estado anterior — sua instância não fica quebrada.

Saída esperada no fim:

OK Amazon SES v7.0.0 installed successfully in 'm7prod'

# Instalando uma versão específica (ou um RC)

Release candidates não aparecem no catálogo — o catálogo lista só versões estáveis. Para instalar um RC, fixe a versão:

mpm install amazonses --instance m7prod --version 7.0.0-rc.1

O mesmo vale para voltar a uma versão anterior.

# 4. Verificar a instalação

mpm list --instance m7prod

E dentro do Mautic — o transport precisa estar registrado no Symfony Mailer:

docker exec mautic7_prod php bin/console debug:container \
  --tag=mailer.transport_factory | grep -i amazon

Deve aparecer AmazonSesTransportFactory. Sem isso, o DSN do próximo passo não vai ser reconhecido.

# 5. Ativar o plugin

Em Configurações → Plugins, abra o card Amazon SES e ligue o toggle de publicação. O plugin nasce despublicado (fail-closed): enquanto estiver desligado, os subscribers e o comando de console se recusam a agir.

# 6. Configurar o envio (DSN)

As credenciais AWS não ficam no plugin — vão no DSN do mailer do Mautic, em Configurações → Email Settings.

Formato:

mautic+ses+api://ACCESS_KEY:SECRET_KEY@default?region=REGION

Exemplo:

mautic+ses+api://AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI%2FK7MDENG@default?region=us-east-1

A SECRET_KEY da AWS costuma conter / e +. Faça URL-encode dela (/ → %2F, + → %2B), senão o DSN é interpretado errado e a autenticação falha com uma mensagem que não ajuda.

# Opções aceitas no DSN

Use as opções do DSN para sobrescrever pontualmente; o ajuste fino do dia a dia fica na aba Settings do plugin.

# 7. Ajustar performance e resiliência

No card do plugin, aba Settings:

Recomendação para produção: ligue o Circuit Breaker. Sem ele, uma queda da SES vira uma sequência de falhas que consome sua quota de envio à toa.

O Custom Endpoint existe para testar sem gastar quota real — aponte para um simulador SES local.

# 8. Testar

Envie um e-mail de teste pelo próprio Mautic (Configurações → Email Settings → Test connection). Se falhar, o log é o primeiro lugar:

docker exec mautic7_prod tail -50 var/logs/mautic_prod-$(date +%Y-%m-%d).php \
  | grep -iE 'CRITICAL|ERROR'

# 9. Manter atualizado

mpm check -i m7prod                 # há versão nova?
mpm update amazonses -i m7prod      # atualiza só este
mpm update all -i m7prod            # atualiza todos

O update usa o mesmo pipeline com backup: se a versão nova quebrar, o rollback devolve a anterior inteira.

# Recuperar e-mails que falharam

O plugin traz um comando para reprocessar eventos de campanha que falharam no envio:

docker exec mautic7_prod php bin/console mautic:amazonses:recover-failed

Ele respeita o gate do plugin: se estiver despublicado, aborta com plugin is not active em vez de agir pela metade.

# Problemas comuns

# "instalou mas não aparece no Mautic"

Quase sempre é o --plugins-dir. Confirme onde ficam os plugins de verdade (passo 1) e recadastre a instância com o caminho certo.

# O card aparece, mas o e-mail não sai

Cheque nesta ordem:

1. O plugin está publicado? (toggle no card)
2. O transport está registrado? (debug:container --tag=mailer.transport_factory)
3. O DSN tem o esquema exato mautic+ses+api://?
4. A secret key está URL-encoded?
5. Sua conta SES saiu do sandbox? No sandbox só dá para enviar para endereços verificados.

# `426 fingerprint_required`

Seu mpm está desatualizado para a API atual:

mpm self-update

# O plugin não aparece em `mpm catalog search`

Se só existe versão RC publicada, ele não entra no catálogo — instale fixando a versão (passo 3).

# Referências

• Tutorial geral do mpm — do container ao update
• Layout do Mautic — docroot e outros knobs
• API key e fingerprint
• Troubleshooting