Dúvidas comuns e solução de problemas no Mautic: guia de troubleshooting
O Mautic é uma plataforma poderosa, mas como qualquer software self-hosted, pode apresentar problemas que exigem diagnóstico e conhecimento técnico para resolver. Neste guia completo de troubleshooting, reunimos as dúvidas mais comuns dos usuários do Mautic e suas soluções práticas — desde problemas de envio de emails até campanhas que não processam e contatos que não aparecem.
Se você está com algum problema no Mautic, este artigo vai te ajudar a identificar e resolver as causas mais frequentes sem precisar abrir um chamado de suporte.
- Problemas mais comuns: Emails não enviados, campanhas não processadas, contatos não rastreados, erros de CRON.
- Primeira verificação: Logs do sistema (Admin → System Info → Log Files).
- Causa raiz mais frequente: CRONs não configurados corretamente.
- Ferramenta de diagnóstico: Admin → System Info → Status para ver o estado geral da instalação.
Problema 1: Emails não estão sendo enviados
Este é de longe o problema mais relatado por usuários do Mautic. As causas são variadas, mas seguem uma ordem lógica de diagnóstico:
Verificar a configuração do servidor de email (SMTP)
Acesse Admin → Configuration → Email Settings e verifique se o SMTP está configurado corretamente. Certifique-se de que o host, porta, usuário e senha estão corretos. Use a função “Test connection” (quando disponível) ou envie um email de teste para verificar. Provedores recomendados: Amazon SES, Mailgun, SendGrid, Postmark.
Verificar o CRON de email
O Mautic não envia emails em tempo real — ele os coloca em uma fila e o CRON mautic:emails:send processa essa fila. Se esse CRON não estiver rodando, os emails ficam acumulados na fila sem serem enviados. Verifique em Admin → System Info → Status se aparece mensagem sobre emails na fila.
Verificar o email como “Campaign Email”
Emails em campanhas precisam ser criados como “Campaign Email” — não como “Template Email”. Se o tipo estiver errado, o email não será enviado pela campanha. Verifique em Channels → Emails → coluna “Type”.
Verificar limites de envio
Se seu plano de SMTP tem limite diário de envios (ex.: 300 emails/dia no Amazon SES sandbox), o Mautic pode estar sendo bloqueado pelo provedor. Verifique os logs do SMTP para identificar erros de limite excedido.
Problema 2: Campanhas não estão processando
Depois do SMTP, os CRONs de campanha são a segunda causa mais comum de problemas. O Mautic precisa de dois CRONs principais para campanhas funcionarem:
php /path/to/mautic/bin/console mautic:campaigns:rebuild— Reconstrói os membros de cada campanha com base nos segmentos.php /path/to/mautic/bin/console mautic:campaigns:trigger— Processa as ações pendentes das campanhas.
Ambos devem rodar com frequência adequada (recomendado: a cada 5 a 15 minutos para o trigger, a cada 30 minutos para o rebuild). Verifique se os CRONs estão configurados no crontab do servidor (Linux) ou no painel de tarefas agendadas do seu host.
No servidor Linux, use
crontab -l -u www-data (ou o usuário do seu servidor web) para listar as tarefas cron configuradas. Se a lista estiver vazia ou os comandos do Mautic não aparecerem, os CRONs não estão configurados. Consulte a documentação oficial do Mautic para a lista completa de CRONs necessários.Problema 3: Contatos não estão sendo rastreados
O Mautic rastreia visitantes do site por meio de um script de tracking (JavaScript) que deve ser inserido em todas as páginas do site. Se o tracking não estiver funcionando:
- Verifique se o script de tracking está inserido no código do site (geralmente no
<head>de todas as páginas). - Certifique-se de que a URL do Mautic no script está correta e acessível publicamente.
- Verifique se o Mautic está configurado em HTTPS, pois scripts mistos (HTTP/HTTPS) são bloqueados pelos navegadores modernos.
- Confirme que não há plugin de cache ou CDN bloqueando o script.
- Desative extensões de bloqueio de anúncios no navegador para testar — o uBlock e outros ad-blockers podem bloquear o script do Mautic.
Problema 4: Segmentos não atualizando
Os segmentos do Mautic são recalculados pelo CRON mautic:segments:update. Se os contatos não estão sendo adicionados ou removidos dos segmentos como esperado:
- Verifique se o CRON
mautic:segments:updateestá rodando. - Confirme que os filtros do segmento estão corretos (verifique os operadores e valores).
- Aguarde o próximo ciclo do CRON — segmentos não são atualizados em tempo real.
- Teste manualmente executando o comando no terminal:
php bin/console mautic:segments:update --id=ID_DO_SEGMENTO.
Problema 5: Página de desinscrição não funciona
Se os links de unsubscribe nos emails não estão funcionando:
- Certifique-se de que a URL pública do Mautic está configurada corretamente em Admin → Configuration → System Settings → Site URL.
- Verifique se o SSL está configurado e se a URL usa HTTPS se o site é HTTPS.
- Confirme que não há regras de firewall ou WAF bloqueando requisições à URL do Mautic.
| Problema | Causa mais comum | Solução rápida |
|---|---|---|
| Emails não enviados | SMTP mal configurado ou CRON ausente | Verificar SMTP e CRON mautic:emails:send |
| Campanhas paradas | CRONs de campanha não rodando | Configurar CRONs rebuild + trigger |
| Contatos não rastreados | Script de tracking ausente ou bloqueado | Verificar script no site e configurações HTTPS |
| Segmentos desatualizados | CRON mautic:segments:update não roda | Configurar CRON ou executar manualmente |
| Erros 500 no Mautic | Memória insuficiente ou erro de banco | Verificar logs em var/logs/mautic_prod.log |
Como verificar os logs do Mautic
Os logs são a principal ferramenta de diagnóstico do Mautic. Acesse Admin → System Info → Log Files para ver os logs mais recentes diretamente no painel. Para acesso completo, os logs ficam em /var/www/html/mautic/var/logs/ (ou equivalente) no servidor. O arquivo mautic_prod.log registra erros de produção — procure por “ERROR” ou “CRITICAL” para identificar problemas.
Perguntas frequentes sobre solução de problemas no Mautic
Mautic está muito lento. O que pode ser?
Performance lenta geralmente indica: servidor subdimensionado (pouca RAM ou CPU), muitos CRONs rodando simultaneamente, banco de dados não otimizado (tabelas muito grandes sem índices adequados), ou cache não configurado. Recomenda-se pelo menos 2 GB de RAM para instalações com até 50.000 contatos. Configure o cache do Mautic (Redis ou Memcached) para melhorar significativamente a performance.
Como limpar a fila de emails acumulados no Mautic?
Execute o CRON mautic:emails:send manualmente para processar a fila imediatamente: php bin/console mautic:emails:send. Se a fila estiver muito grande e você quiser descartá-la, é possível limpar a tabela email_stats diretamente no banco de dados, mas isso remove o histórico de envios. Proceda com cuidado e faça backup antes.
Mautic não abre após atualização. Como resolver?
Após atualizações, é comum precisar limpar o cache: acesse via SSH e execute php bin/console cache:clear. Se o erro persistir, verifique o log de erros, confira se as permissões de arquivo estão corretas (chmod -R 755 var/) e se as dependências PHP foram atualizadas (composer install).
Por que os emails do Mautic caem no spam?
As causas mais comuns são: domínio sem SPF, DKIM e DMARC configurados corretamente, uso de IPs com reputação baixa, conteúdo com palavras de spam, taxa de bounces alta ou falta de link de unsubscribe. Configure os registros de autenticação de email (SPF, DKIM, DMARC) no DNS do seu domínio como primeiro passo.
Onde encontrar ajuda para problemas do Mautic?
A comunidade do Mautic é ativa e gratuita. Os principais recursos são: documentação oficial em docs.mautic.org, fórum da comunidade em community.mautic.org, grupos no Slack (Mautic Community), e repositório GitHub para reportar bugs. Para suporte comercial, existem parceiros certificados Mautic em diversos países.
Conclusão
A maioria dos problemas no Mautic tem causa identificável e solução prática. O diagnóstico começa sempre pelos logs e pela verificação dos CRONs — as duas fontes de 80% dos problemas relatados pela comunidade. Com o ambiente configurado corretamente (CRONs, SMTP, tracking e HTTPS), o Mautic opera de forma estável e confiável.
Se o problema persistir após seguir as soluções acima, a comunidade do Mautic é um excelente recurso — com milhares de usuários e desenvolvedores que provavelmente já enfrentaram o mesmo desafio. Para mais conteúdos sobre Mautic, acesse os artigos de Mautic no atraca.com.br ou visite o fórum oficial da comunidade Mautic.
Perguntas frequentes sobre problemas comuns no Mautic (FAQ)
Por que meus emails do Mautic não estão sendo enviados?
Verifique a configuração SMTP nas definições de email, confirme que os CRON jobs estão ativos (especialmente mautic:emails:send) e cheque os logs em app/logs para identificar erros específicos.
O Mautic está lento, o que fazer?
Ative cache com Redis ou Memcached, aumente a memória PHP para 512 MB ou mais, otimize o banco de dados e verifique se os CRON jobs não estão sobrecarregando o servidor.
Como resolver erro 500 no Mautic?
Verifique os logs do Apache/Nginx e do Mautic em app/logs. Causas comuns incluem falta de memória PHP, permissões incorretas de arquivos ou extensões PHP ausentes.
Os formulários do Mautic não aparecem no site, por quê?
Verifique se o código de embed está correto, se não há conflitos de JavaScript no site e se a URL do Mautic está acessível externamente.
O rastreamento de visitantes não funciona, como corrigir?
Confirme que o código JavaScript de tracking está inserido corretamente, que o domínio do Mautic está nas configurações de CORS e que não há bloqueadores de script ativos.
