Instalação e configuração do Mautic: o passo a passo completo

Instalar o Mautic é a parte rápida e fácil; o que separa uma instalação que entrega e-mail na caixa de entrada de uma que cai no spam — ou nem chega a enviar — são quatro camadas de configuração pós-instalação: permissões de arquivo, SMTP, os registros DNS de autenticação (SPF, DKIM e DMARC) e o cron. É por isso que este guia gasta mais tempo depois do instalador do que antes dele.

Se o que você procura é comparar os métodos de instalação (VPS, Docker, painel ou auto-instalador), o lugar certo é como instalar o Mautic. Aqui o foco é o que vem em seguida: transformar uma instalação que apenas "subiu" numa plataforma que envia, rastreia e entrega. O caminho completo é este:

Requisitos de servidor para o Mautic

Antes de instalar, confirme que o servidor atende a todos os requisitos. Especificações abaixo do mínimo — em especial hospedagem compartilhada — são a causa mais comum de lentidão e de erros intermitentes que dão trabalho para diagnosticar depois.

Como referência de dimensionamento: uma base de até 10 mil contatos roda bem num VPS com 2 vCPUs e 4 GB de RAM. Ao passar de algumas dezenas de milhares de contatos, mova o banco de dados para um servidor separado e considere um cache em memória (Redis) para aliviar a carga.

Instalando o Mautic

A instalação em si tem dois caminhos principais. Escolha um — não os dois.

Opção 1: pacote ZIP + instalador web

Bom para quem prefere seguir por uma interface gráfica:

1. Baixe o pacote da versão estável mais recente em mautic.org/download.
2. Faça upload do ZIP e extraia na raiz do domínio (por exemplo, /var/www/mautic).
3. Crie o banco de dados: CREATE DATABASE mautic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
4. Ajuste as permissões (veja a seção seguinte — este é o passo mais esquecido).
5. Acesse o domínio no navegador; o instalador web assume a partir daí.

Opção 2: instalação via Composer

O caminho recomendado hoje para ambientes de produção e para quem versiona a instalação. O comando de instalação exige a URL do site como argumento — sem ela, o mautic:install não roda:

composer create-project mautic/recommended-project:^5 mautic --no-interaction
cd mautic
php bin/console mautic:install https://mautic.seudominio.com.br --force \
  --db_driver=pdo_mysql \
  --db_host=localhost \
  --db_name=mautic \
  --db_user=mautic_user \
  --db_password=SENHA \
  --admin_email=seu@email.com \
  --admin_password=SENHA_ADMIN

Repare que o console fica em bin/console (e não em app/console, como em versões antigas do Mautic). Todos os comandos deste guia usam esse caminho.

Permissões de arquivo: o passo que gera a maioria dos erros 500

Este é o detalhe que trava mais instalações e quase nunca aparece nos tutoriais. O Mautic precisa gravar cache, logs e arquivos enviados em disco. Se o usuário do servidor web não for dono dessas pastas, o resultado é um erro 500 em branco logo depois de instalar — sem mensagem clara.

As pastas que precisam ser graváveis pelo usuário do servidor web (normalmente www-data no Debian/Ubuntu) são:

• var/ — abriga cache/, logs/ e spool/ (a fila de e-mails).
• config/ — onde o Mautic grava o local.php com as credenciais.
• media/ — imagens, anexos e arquivos enviados pelo painel.

Ajuste dono e permissões assim:

sudo chown -R www-data:www-data /var/www/mautic
sudo find /var/www/mautic -type d -exec chmod 755 {} \;
sudo find /var/www/mautic -type f -exec chmod 644 {} \;

Se depois da instalação surgir um erro 500, o primeiro reflexo deve ser conferir o dono das pastas acima e ler o log de erro do servidor web (/var/log/nginx/error.log ou /var/log/apache2/error.log) e o log do Mautic em var/logs/mautic_prod.log. Para os erros mais comuns além desse, veja dúvidas comuns e solução de problemas no Mautic.

Configurando o servidor web (Apache)

Um virtual host mínimo em Apache, já com HTTPS, fica assim:

<VirtualHost *:443>
  ServerName mautic.seudominio.com.br
  DocumentRoot /var/www/mautic
  <Directory /var/www/mautic>
    AllowOverride All
    Require all granted
  </Directory>
  SSLEngine on
  SSLCertificateFile /etc/ssl/certs/mautic.crt
  SSLCertificateKeyFile /etc/ssl/private/mautic.key
</VirtualHost>

O AllowOverride All é o que permite ao .htaccess do Mautic reescrever as URLs; sem ele, as páginas internas retornam 404. Em Nginx a configuração é diferente — o passo a passo dela está no guia de como instalar o Mautic.

Configurando os cron jobs

Os cron jobs são o motor do Mautic: sem eles, a interface abre e os contatos entram, mas nada é processado — os e-mails não saem e os segmentos não atualizam. Quatro comandos formam o núcleo, e a ordem entre eles não é opcional, porque cada um depende do resultado do anterior:

Agende-os sempre pelo crontab do sistema (crontab -e), nunca pelo agendador interno do Mautic, que depende de alguém acessando a aplicação:

*/15 * * * * php /var/www/mautic/bin/console mautic:segments:update --no-interaction
*/15 * * * * php /var/www/mautic/bin/console mautic:campaigns:rebuild --no-interaction
*/15 * * * * php /var/www/mautic/bin/console mautic:campaigns:trigger --no-interaction
*/5 * * * * php /var/www/mautic/bin/console mautic:emails:send --no-interaction

Para produção, escalone os minutos de cada comando do núcleo (para respeitar a dependência), proteja cada linha com flock e use o caminho completo do PHP. Esses detalhes — mais os crons de manutenção, como email:fetch para bounces e maintenance:cleanup para limpeza — estão detalhados em quais crons o Mautic precisa.

Configuração de e-mail e entregabilidade

Sem SMTP configurado, o Mautic não envia e-mail nenhum. Acesse Configurações → Email Settings e aponte para um serviço de envio transacional — Amazon SES, Mailgun ou similar. Todos cobram por volume, a valores baixos por milhares de e-mails, e entregam muito melhor do que o sendmail de um VPS comum.

Usando o Amazon SES, por exemplo, os campos são:

• Server: email-smtp.us-east-1.amazonaws.com (ou o host da sua região)
• Port: 587 (STARTTLS)
• Username / Password: as credenciais SMTP geradas no painel do SES

Os três registros DNS que decidem se o e-mail chega

Configurar o SMTP faz o e-mail sair; são os registros de autenticação no DNS do seu domínio que fazem ele chegar na caixa de entrada em vez do spam. Os três são obrigatórios na prática:

• SPF — autoriza o provedor a enviar em nome do seu domínio. Exemplo: v=spf1 include:amazonses.com ~all
• DKIM — assina digitalmente cada mensagem para provar que não foi adulterada. O SES e o Mailgun fornecem as chaves (em geral como registros CNAME) para você publicar no DNS.
• DMARC — diz ao servidor de destino o que fazer quando SPF ou DKIM falham. Comece em modo observação: v=DMARC1; p=none; rua=mailto:dmarc@seudominio.com.br

Este é o ponto que mais derruba operações inteiras: um SMTP impecável com DNS incompleto ainda cai no spam. Faça os três antes de disparar a primeira campanha.

Domínio, HTTPS e rastreamento

O Mautic precisa de HTTPS para funcionar em produção. Sem SSL, o script de rastreamento é bloqueado pelos navegadores por conteúdo misto e os links dos e-mails são marcados como inseguros. Use o Let's Encrypt (gratuito) para o certificado — o certbot automatiza o processo em servidores Ubuntu/Debian.

Com o SSL ativo, ajuste em Configurações:

• Site URL: a URL completa do Mautic, com HTTPS. É a partir dela que o Mautic monta o script de rastreamento e os links dos e-mails.
• Timezone e Locale: fuso e localização para o Brasil, para os agendamentos baterem com o horário local.
• Unsubscribe Message: a mensagem de descadastro em português.
• Bounce Handling: a caixa de e-mail que receberá os retornos, para o Mautic higienizar a base automaticamente.

Depois disso, é só instalar o script de rastreamento no seu site — o mesmo que integra o Mautic ao WordPress.

Perguntas frequentes sobre instalação do Mautic

Quais são os requisitos mínimos para instalar o Mautic?

O Mautic 5 exige PHP 8.x (a documentação lista 8.0 em diante, com as versões mais recentes recomendadas), MySQL 5.7+ ou MariaDB 10.4+, e um servidor web Apache com mod_rewrite ou Nginx. As extensões de PHP curl, gd, imap, intl, mbstring, mysqli/pdo_mysql, xml, zip e bcmath precisam estar habilitadas. Reserve pelo menos 2 GB de RAM e um disco SSD; hospedagem compartilhada não é recomendada.

Preciso configurar SPF, DKIM e DMARC mesmo usando Amazon SES ou Mailgun?

Sim. O serviço transacional só entrega o e-mail ao servidor de destino — quem decide se ele cai na caixa de entrada ou no spam é a autenticação do seu domínio. SPF autoriza o provedor a enviar em nome do domínio, DKIM assina cada mensagem e DMARC diz ao destinatário o que fazer quando um dos dois falha. Sem esses três registros no DNS, mesmo um SMTP bem configurado tende a ser marcado como spam.

Quais permissões de pasta o Mautic exige e por que dão erro 500?

O usuário do servidor web (normalmente www-data no Debian/Ubuntu) precisa ser dono dos arquivos e ter permissão de escrita em var/ (cache, logs e spool), config/ e media/. Quando essas pastas ficam com dono ou permissão errados, o Mautic não consegue gravar o cache nem os logs e responde com erro 500 em branco. O primeiro passo ao ver esse erro é conferir o dono das pastas e o log de erro do servidor web.

Posso instalar o Mautic no mesmo servidor do WordPress?

Tecnicamente sim, mas não é recomendado para produção. O Mautic e o WordPress disputam CPU, RAM e MySQL, e a queda de performance atinge os dois. Para testes ou volume baixo é viável; para produção com envio real de e-mail, use servidores separados ou pelo menos bancos de dados separados.

Como faço o Mautic reconhecer meu domínio e ativar o rastreamento?

Em Configurações, defina o campo Site URL com o endereço completo em HTTPS (por exemplo, https://mautic.seudominio.com.br). É essa URL que o Mautic usa para gerar o script de rastreamento e os links dos e-mails. Sem HTTPS o script de tracking é bloqueado pelos navegadores por conteúdo misto, então o certificado SSL precisa estar ativo antes de você instalar o código de acompanhamento no site.

Conclusão

Uma instalação bem feita do Mautic é o alicerce de toda a operação de automação de marketing. A instalação em si leva poucos minutos; o que sustenta a plataforma no longo prazo são as quatro camadas seguintes — permissões corretas, SMTP configurado, os registros DNS de autenticação e o cron rodando na ordem certa. É nesse conjunto que se decide se os e-mails chegam na caixa de entrada.

Feita a configuração, avance com calma: comece por formulários e e-mails simples antes de montar campanhas complexas. Para seguir, veja o que é o Mautic para entender a plataforma a fundo, email marketing com Mautic para os primeiros envios, ou consulte a documentação oficial de instalação do Mautic para as referências de cada etapa.