Dúvidas comuns e solução de problemas no Mautic

A maioria dos problemas no Mautic não é aleatória: eles se repetem em quatro focos — e-mails que não saem, campanhas que não disparam, tracking que não registra e erros 500 — e quase todos têm a mesma raiz, um cron parado ou uma configuração de servidor errada. Como o Mautic é uma aplicação self-hosted baseada em filas, o sintoma que aparece na interface quase nunca é a causa: a causa está no log, no crontab ou no SMTP. Este guia é o companheiro de troubleshooting dos outros artigos da série — em vez de ensinar a configurar, ele ensina a diagnosticar quando algo que já estava configurado para de funcionar.

Na prática, quando um Mautic que eu opero em produção para de enviar, eu não saio clicando na interface: eu abro o log primeiro. É de lá que sai a resposta em 80% dos casos.

Antes de tudo: o log é o ponto de partida

Os logs são a principal ferramenta de diagnóstico do Mautic — e o primeiro lugar onde olhar, sempre. No Mautic atual, os logs de aplicação ficam em var/logs/, e o arquivo de produção é o mautic_prod.log. No servidor, o caminho completo costuma ser algo como /var/www/mautic/var/logs/mautic_prod.log.

Se você não tem acesso ao terminal, dá para consultar as últimas linhas pela própria interface, no menu de engrenagem, em System Info. Em qualquer um dos dois caminhos, a técnica é a mesma: procure pelas palavras ERROR e CRITICAL. Elas apontam a exceção exata — uma falha de conexão SMTP, um erro de banco, uma permissão negada — que quase sempre explica o sintoma visível. Só depois de ler o log você sabe se está diante de um problema de e-mail, de cron ou de servidor.

Problema 1: e-mails não saem

Este é, de longe, o problema mais relatado. Ele quase nunca tem uma única causa — siga a ordem abaixo.

A fila e o cron de envio. O Mautic pode enviar em modo fila (spool): em vez de entregar cada e-mail na hora, ele o acumula e deixa o cron mautic:emails:send despachar o lote para o SMTP. Se esse comando não roda, os e-mails se acumulam e nada sai. Para esvaziar a fila na hora, execute:

php bin/console mautic:emails:send --no-interaction

Se isso resolve, o problema era o cron: agende o comando no crontab. Se você usa envio síncrono (sem fila), esse cron não é necessário — mas aí a suspeita vira o SMTP.

A configuração do SMTP. Em Configuration → Email Settings, confira host, porta, usuário e senha. Use o envio de e-mail de teste para validar e provedores transacionais de boa reputação, como Amazon SES, Mailgun, SendGrid ou Postmark. Atenção aos limites: o sandbox do Amazon SES, por exemplo, só entrega 200 mensagens por período de 24 horas e apenas para endereços verificados — enquanto sua conta não sai do sandbox, o SES bloqueia o resto e o Mautic registra o erro no log.

O tipo do e-mail. E-mails usados dentro de campanhas precisam ser criados como Campaign Email, não como Template Email. Se o tipo estiver errado, a campanha simplesmente não envia. Confira a coluna Type em Channels → Emails. Para montar o fluxo corretamente, veja criando campanhas de marketing no Mautic.

Problema 2: campanhas não disparam

Depois do SMTP, os crons de campanha são a segunda causa mais comum. As campanhas dependem de três comandos que precisam rodar na ordem certa, porque cada um usa o resultado do anterior:

1. mautic:segments:update — recalcula quem está em cada segmento.
2. mautic:campaigns:rebuild — decide quem entra ou sai de cada campanha com base nesses segmentos.
3. mautic:campaigns:trigger — dispara as ações pendentes (enviar e-mail, aplicar tag, ajustar pontos).

Se algum não roda, ou se rodam fora de ordem, o contato até entra na campanha, mas nenhuma ação acontece — o clássico "configurei tudo e não dispara". Confirme o que está agendado com:

crontab -l -u www-data

Troque www-data pelo usuário do seu servidor web. Se a lista estiver vazia ou os comandos do Mautic não aparecerem, os crons não estão configurados. Este é um assunto que merece atenção por si só: a lista completa, os intervalos e o porquê da ordem estão em quais crons o Mautic precisa. Uma dica que evita dor de cabeça: proteja cada linha com flock para uma execução não atropelar a anterior.

Problema 3: o tracking não registra visitantes

O Mautic acompanha as visitas ao seu site por um script de tracking, o mtc.js, que precisa estar em todas as páginas. Quando ele não registra nada, verifique nesta ordem:

• O snippet está colado antes do </body> em todas as páginas (o jeito mais seguro de obtê-lo é copiar o embed de um formulário, que já inclui o tracking).
• A URL do Mautic no script está correta e é acessível publicamente.
• O site e o Mautic usam HTTPS. Conteúdo misto (site em HTTPS carregando script em HTTP) é bloqueado pelos navegadores modernos.
• Nenhum plugin de cache ou CDN está removendo ou adiando o script.
• Para testar sem ruído, desative bloqueadores de anúncios — o uBlock e similares costumam barrar o mtc.js.

Lembre também que o tracking só associa a visita a um contato depois que a pessoa se identifica (envia um formulário ou clica num link rastreado de e-mail). Antes disso, a visita entra como anônima — o que é o comportamento esperado, não um defeito. Os detalhes de como isso funciona estão em rastreamento de atividades e pontuação de leads no Mautic.

Problema 4: contatos não entram nos segmentos

Os segmentos dinâmicos são recalculados pelo cron mautic:segments:update. Se um contato que deveria estar num segmento não aparece nele:

• Confirme que o cron mautic:segments:update está rodando — segmentos não atualizam em tempo real.
• Revise os filtros do segmento, prestando atenção aos operadores (igual, contém, maior que) e aos valores exatos dos campos.
• Force o recálculo agora, sem esperar o próximo ciclo:

php bin/console mautic:segments:update --no-interaction

Se o contato entra no segmento depois desse comando manual, está confirmado: faltava o cron agendado.

Problema 5: erro 500, cache e permissões

Erro 500 costuma aparecer logo após uma atualização de versão. O log em var/logs/mautic_prod.log mostra a exceção real, mas as três causas mais frequentes são:

• Cache velho. Limpe com php bin/console cache:clear.
• Permissão da pasta var/. As subpastas var/cache, var/logs e var/spool precisam ser graváveis pelo usuário do servidor web. Ajuste com chown -R www-data:www-data var/ (usando o usuário correto da sua instalação).
• Migração de banco pendente. Se a atualização não concluiu as migrações, o painel quebra. Rode php bin/console doctrine:migrations:migrate --no-interaction para aplicá-las.

Para importações grandes ou tarefas que estouram no meio, o gargalo quase sempre é o PHP: aumente o memory_limit (512 MB é um bom piso) e rode o trabalho pesado pela linha de comando, não pela interface, para não esbarrar no max_execution_time do servidor web.

Tabela de diagnóstico rápido

Perguntas frequentes sobre problemas no Mautic

Por que meus e-mails do Mautic ficam presos na fila e não saem?

No modo fila, o Mautic não entrega o e-mail na hora: ele o deixa no spool e é o cron mautic:emails:send que despacha para o SMTP. Se esse comando não roda, a fila só cresce. Rode php bin/console mautic:emails:send manualmente para esvaziá-la na hora e, em seguida, agende o comando no crontab. Se mesmo assim nada sai, o problema está no SMTP (host, porta, usuário ou senha errados) ou num limite do provedor — cheque o log em var/logs/mautic_prod.log.

Onde ficam os logs do Mautic e o que devo procurar neles?

No Mautic atual, os logs de aplicação ficam em var/logs, e o arquivo de produção é var/logs/mautic_prod.log. Você também consulta as últimas linhas pela interface, no menu de engrenagem, em System Info. Procure pelas palavras ERROR e CRITICAL: elas apontam a exceção exata (falha de SMTP, erro de banco, permissão negada) que costuma explicar o sintoma que você vê na tela.

Configurei tudo, mas a campanha não dispara. O que verifico primeiro?

Quase sempre é cron. As campanhas dependem de três comandos na ordem certa: mautic:segments:update, depois mautic:campaigns:rebuild e por fim mautic:campaigns:trigger. Se algum não roda ou roda fora de ordem, o contato entra na campanha mas nenhuma ação acontece. Confirme o que está agendado com crontab -l -u www-data e verifique se o e-mail da campanha foi criado como Campaign Email, não como Template Email.

Por que os e-mails do Mautic caem no spam?

As causas mais comuns são o domínio sem SPF, DKIM e DMARC configurados no DNS, o uso de um IP com reputação baixa, conteúdo com cara de spam, taxa de bounces alta ou ausência de link de descadastro. Configure primeiro os registros de autenticação (SPF, DKIM e DMARC) no DNS e use um SMTP transacional com boa reputação, como Amazon SES, Mailgun ou Postmark.

O Mautic ficou lento ou está dando erro 500. Como diagnostico?

Comece pelo log em var/logs/mautic_prod.log, que mostra a exceção real. Erro 500 costuma ser falta de memória do PHP, permissão da pasta var/ ou migração de banco pendente após uma atualização: limpe o cache com php bin/console cache:clear e garanta que var/ é gravável pelo usuário do servidor web. Lentidão geralmente é servidor subdimensionado, banco sem índices ou cache desligado — considere pelo menos 2 GB de RAM e ative um cache como Redis.

Conclusão

A maioria dos problemas no Mautic tem causa identificável e solução prática, e o método é sempre o mesmo: leia o log antes de tocar em qualquer configuração, confirme os crons e só então parta para SMTP, tracking ou permissões. Com o ambiente bem montado — crons na ordem, SMTP autenticado, tracking em HTTPS e a pasta var/ gravável —, o Mautic roda de forma estável por meses sem intervenção.

Se você está montando a instalação agora, comece por como instalar o Mautic e por como criar formulários no Mautic para capturar os primeiros contatos. E quando o problema não ceder, a referência definitiva é a documentação oficial do Mautic, com uma comunidade ativa que provavelmente já resolveu o mesmo caso.