Quais crons o Mautic precisa

Um Mautic recém-instalado, sem crons configurados, parece funcionar: a interface abre, os contatos entram, as campanhas são desenhadas. Mas nada acontece de fato — os e-mails não saem, os segmentos não atualizam e os leads ficam parados no meio do fluxo. A tese em uma frase: os crons não são um detalhe da instalação, são o motor que executa tudo o que você configura no Mautic, e a ordem em que rodam (segmentos, depois campanhas, depois envio) importa tanto quanto o fato de rodarem.

O que é um cron e por que o Mautic depende dele

Cron é o agendador de tarefas do Linux que executa comandos em intervalos definidos. O Mautic depende dele porque é uma aplicação baseada em filas: em vez de processar cada ação no exato instante em que o evento acontece — o que exigiria um processo rodando o tempo todo —, ele acumula o trabalho e o executa em lotes quando o comando correspondente é chamado.

A consequência prática é que existe sempre uma defasagem entre o evento (um lead preenche um formulário) e a ação (o e-mail de boas-vindas sai). Essa defasagem é igual ao intervalo do cron — por isso os comandos mais sensíveis ao tempo rodam em intervalos curtos. Sempre agende esses comandos pelo crontab do sistema operacional, e não pelo agendamento interno do próprio Mautic: o crontab é mais confiável, roda mesmo sem ninguém acessando a aplicação e não depende de uma requisição web para disparar.

Os crons essenciais do Mautic (na ordem certa)

Três comandos formam o núcleo da automação, e a ordem entre eles não é opcional — cada um depende do resultado do anterior.

1. mautic:segments:update — atualiza os segmentos

Recalcula quais contatos pertencem a cada segmento dinâmico, aplicando todos os filtros configurados. Um contato que acabou de atingir a pontuação de um segmento VIP só passa a fazer parte dele depois que este comando roda. Por ser a base de tudo, é o primeiro a executar.

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

2. mautic:campaigns:rebuild — recalcula quem está em cada campanha

Compara os segmentos e formulários que alimentam cada campanha e adiciona ou remove contatos conforme as mudanças. Um lead que entrou num segmento-fonte só começa a percorrer o fluxo depois que o rebuild o inclui na campanha — e ele só enxerga a atualização se o segments:update já tiver rodado antes. Por isso é o segundo. (Nas versões atuais este comando também é exposto como mautic:campaigns:update.)

php /var/www/mautic/bin/console mautic:campaigns:rebuild --no-interaction

3. mautic:campaigns:trigger — dispara as ações das campanhas

Executa as ações agendadas do fluxo de automação: enfileira e-mails de campanha, aplica tags, ajusta pontuação e avança os contatos pelas decisões. Como ele age sobre quem o rebuild já colocou na campanha, é o terceiro da sequência.

php /var/www/mautic/bin/console mautic:campaigns:trigger --no-interaction

4. mautic:emails:send — esvazia a fila de e-mails

Quando você configura o envio em modo fila (spool), o Mautic não entrega os e-mails na hora: ele os deixa em fila, e este comando é quem os despacha para o SMTP. O campaigns:trigger coloca o e-mail na fila; o emails:send faz o envio. Se você não usa o modo fila, o envio é síncrono e este cron não é necessário — mas em qualquer operação de volume, a fila é o que evita travar a interface.

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

Crons de manutenção e opcionais

Além do núcleo, alguns comandos mantêm a operação saudável — nem todos são necessários em toda instalação:

• mautic:email:fetch — conecta à caixa monitorada e processa bounces e respostas. Essencial para a higiene da base e a reputação do domínio. (Repare: o comando de envio é emails:send, no plural, mas o de leitura é email:fetch, no singular.)
• mautic:broadcasts:send — envia os e-mails de segmento (broadcast) agendados.
• mautic:messages:send — processa a fila de mensagens de marketing agendadas.
• mautic:webhooks:process — esvazia a fila de webhooks quando eles estão em modo fila.
• mautic:import — executa importações grandes em segundo plano.
• mautic:iplookup:download — atualiza a base GeoIP (MaxMind) usada para localizar contatos.
• mautic:maintenance:cleanup — remove logs de eventos e dados de rastreamento antigos para o banco não crescer sem controle. Aceita --days-old para definir o corte.

Como configurar os crons no crontab do Linux

Edite o crontab do usuário que roda o Mautic (normalmente www-data no Debian/Ubuntu). Como usar outro usuário exige privilégio, faça isso com sudo:

sudo crontab -u www-data -e

Cole as linhas abaixo. Note três detalhes: os minutos do núcleo estão escalonados (0/15/30/45, depois 5/20/35/50, depois 10/25/40/55) para respeitar a ordem de dependência; cada comando roda dentro de flock -n, que impede uma nova execução de começar enquanto a anterior não terminou; e a saída vai para um log dedicado.

# Núcleo — escalonado para respeitar a ordem: segments -> rebuild -> trigger
0,15,30,45 * * * * flock -n /tmp/mautic-segments.lock /usr/bin/php /var/www/mautic/bin/console mautic:segments:update --no-interaction >> /var/log/mautic-cron.log 2>&1
5,20,35,50 * * * * flock -n /tmp/mautic-rebuild.lock /usr/bin/php /var/www/mautic/bin/console mautic:campaigns:rebuild --no-interaction >> /var/log/mautic-cron.log 2>&1
10,25,40,55 * * * * flock -n /tmp/mautic-trigger.lock /usr/bin/php /var/www/mautic/bin/console mautic:campaigns:trigger --no-interaction >> /var/log/mautic-cron.log 2>&1

# Envio da fila de e-mails
*/5 * * * * flock -n /tmp/mautic-emails.lock /usr/bin/php /var/www/mautic/bin/console mautic:emails:send --no-interaction >> /var/log/mautic-cron.log 2>&1

# Manutenção
*/15 * * * * flock -n /tmp/mautic-fetch.lock /usr/bin/php /var/www/mautic/bin/console mautic:email:fetch --no-interaction >> /var/log/mautic-cron.log 2>&1
0 4 1 * *   /usr/bin/php /var/www/mautic/bin/console mautic:iplookup:download --no-interaction >> /var/log/mautic-cron.log 2>&1
0 2 * * 0   /usr/bin/php /var/www/mautic/bin/console mautic:maintenance:cleanup --days-old=365 --no-interaction >> /var/log/mautic-cron.log 2>&1

Use sempre o caminho completo do PHP e do console. O crontab não herda as variáveis de ambiente do seu shell, então php pode nem ser encontrado. Descubra o caminho com which php — costuma ser /usr/bin/php ou algo como /usr/bin/php8.1 — e aponte também o console completo (/var/www/mautic/bin/console). A flag --no-interaction evita que o comando fique esperando uma confirmação que nunca virá.

Como verificar se os crons estão rodando

Depois de salvar, confirme que os comandos estão de fato executando:

• Confira o crontab: sudo crontab -l -u www-data mostra exatamente o que foi agendado.
• Log dedicado: tail -f /var/log/mautic-cron.log acompanha cada execução em tempo real.
• Log do Mautic: tail -f /var/www/mautic/var/logs/mautic_prod.log mostra a atividade interna e eventuais erros.
• Painel Admin: em Configurações → Log do sistema você consulta os registros pela própria interface.
• Teste de ponta a ponta: adicione um contato ao segmento-fonte de uma campanha e aguarde alguns minutos; o e-mail de boas-vindas deve chegar dentro da janela dos intervalos configurados.

Conclusão

Os crons são o que faz o Mautic sair do papel: sem eles, você tem uma ferramenta de automação que não automatiza nada. Configure o núcleo na ordem certa (segments:update → campaigns:rebuild → campaigns:trigger), acrescente o emails:send e os comandos de manutenção, proteja cada linha com flock e verifique os logs sempre que atualizar a versão ou mexer no servidor. É a diferença entre uma instalação que respira e uma que só ocupa disco.

Para ir além, veja como instalar o Mautic, aprenda a montar seus fluxos em criando campanhas de marketing no Mautic ou consulte o guia definitivo do Mautic. A referência oficial dos comandos está na documentação de cron jobs do Mautic.

Perguntas frequentes sobre os crons do Mautic

Em que ordem os crons do Mautic devem rodar?

A dependência é mautic:segments:update, depois mautic:campaigns:rebuild e por fim mautic:campaigns:trigger. Os segmentos precisam estar atualizados antes de o rebuild decidir quem entra em cada campanha, e o rebuild precisa ter rodado antes de o trigger disparar as ações. Escalone os horários (por exemplo, segments nos minutos 0, 15, 30 e 45, rebuild em 5, 20, 35 e 50, e trigger em 10, 25, 40 e 55) para garantir a ordem sem que um comando atropele o outro.

Posso usar o agendador do cPanel em vez do crontab do Linux?

Sim. O agendador de tarefas do cPanel roda os mesmos comandos bin/console; a diferença é que você preenche o intervalo pela interface web em vez do terminal. Confirme qual usuário do sistema executa os scripts na sua hospedagem e ajuste as permissões dos arquivos do Mautic para esse usuário. Em VPS com acesso root, o crontab pelo terminal continua sendo a opção mais confiável e transparente.

Por que o Mautic processa as ações com atraso mesmo com o cron configurado?

O atraso mínimo é sempre igual ao intervalo do cron: com execução a cada 15 minutos, uma ação pode levar até 15 minutos para acontecer. Se o atraso for maior que o intervalo, normalmente é porque uma execução ainda não terminou quando a próxima começou, ou porque o comando esbarrou no limite de memória do PHP. Proteja cada linha com flock para não sobrepor execuções e verifique o log do Mautic para descartar erros de memória.

Preciso dos crons se usar o Mautic hospedado?

Não. Na versão hospedada (Mautic Cloud, em mautic.com) toda a infraestrutura, incluindo os crons, é gerenciada pela plataforma. A configuração de crons via crontab só é necessária no Mautic self-hosted, em que você administra o próprio servidor.

O Mautic tem um painel para monitorar os crons?

Não existe um dashboard nativo de monitoramento de crons. Para saber se um comando deixou de rodar, use um serviço externo como Healthchecks.io ou Cronitor: cada cron envia um ping ao terminar e você recebe um alerta quando o ping não chega no intervalo esperado. Basta acrescentar uma chamada curl com a URL de ping ao final da linha do cron.