Hospedar Listmonk em um VPS gerenciado: suas newsletters em seu servidor

O que o Listmonk faz

O Listmonk gerencia suas listas de distribuição e suas newsletters a partir de uma interface web. É um programa único, escrito em Go, cuja única dependência é o PostgreSQL. As listas dele são de mão única: você escreve a seus assinantes, e não se trata de uma lista de discussão entre eles.

• As listas: listas em simple ou double opt-in, até milhões de assinantes, e uma segmentação por expressões SQL sobre os atributos deles.
• As campanhas: um editor visual de arrastar e soltar, um editor WYSIWYG, Markdown, HTML ou texto simples, e modelos na linguagem Go com mais de 100 funções.
• As estatísticas: aberturas, cliques, bounces e links mais acessados, campanha por campanha.
• As mensagens transacionais: uma API para enviar uma mensagem a partir de um modelo, por exemplo uma confirmação de pedido. “Messengers” em webhook HTTP também abrem o SMS ou o WhatsApp, a conectar ao serviço de sua escolha.
• Os assinantes: uma página em que cada um gerencia suas preferências, exporta seus dados ou os apaga.
• A equipe: funções e permissões precisas, o login único OIDC e tokens de API limitados.
• As mídias: uma biblioteca de imagens no disco ou em um armazenamento compatível com S3.

O que a licença AGPL-3.0 permite

O Listmonk é publicado sob a licença GNU AGPL versão 3. Você pode usá-lo, inclusive em uma empresa, e enviar suas campanhas e as de seus clientes, sem licença a comprar. Resta o custo do servidor e o de seu serviço de envio.

O artigo 13 acrescenta uma condição própria da AGPL: se você modificar o programa, sua versão deve propor claramente a todos que a usam à distância, pela rede, obter o código-fonte dela, gratuitamente. Se você distribuir cópias, as obrigações de compartilhamento de código da licença também se aplicam. Rodar o Listmonk sem modificá-lo não aciona esse artigo.

Qual versão do Listmonk instalar?

Um ponto a conhecer antes de começar. No GitHub, a etiqueta “Latest” designa neste momento a v7.0.0-beta.2, de 10 de novembro de 2026, que o próprio projeto apresenta como uma beta. A última versão estável é a v6.2.0, que traz correções de segurança nas permissões. Em 11 de novembro de 2026, a imagem Docker latest designa essa v6.2.0.

A versão 7 substitui toda a interface de administração, muda alguns endereços dela, transforma a configuração app.from_email em uma lista de endereços e modifica chaves de tradução, o que afeta os modelos personalizados. Leia as notas de versão dela antes de passar para ela.

O arquivo Compose do projeto executa --upgrade --yes a cada inicialização: uma nova imagem migra o banco sem perguntar. Ora, um banco migrado não pode ser relido por uma versão mais antiga, e voltar atrás obriga a restaurar um backup. Com uma tag fixa, como v6.2.0, a mudança de versão continua sendo decisão sua.

A instalação com Docker Compose

O projeto recomenda o Docker Compose: o arquivo dele inicia o Listmonk e o PostgreSQL juntos. Em um servidor com o Docker instalado, crie uma pasta e baixe esse arquivo:

mkdir listmonk
cd listmonk
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml

O projeto pede para adaptar esse arquivo a seu ambiente. Estas são as únicas linhas a mudar, o restante não se mexe:

x-db-credentials: &db-credentials
  POSTGRES_USER: &db-user listmonk
  POSTGRES_PASSWORD: &db-password un-mot-de-passe-long
  POSTGRES_DB: &db-name listmonk

services:
  app:
    image: listmonk/listmonk:v6.2.0
    ports:
      - "127.0.0.1:9000:9000"
    hostname: listmonk.example.com

• A senha do banco: o arquivo fornece listmonk como valor inicial. Mude-a antes da primeira execução, pois a imagem PostgreSQL só lê essa variável em uma pasta de dados vazia.
• A imagem: uma versão precisa no lugar de latest, pela razão vista acima.
• A porta publicada em 127.0.0.1: é uma adaptação nossa. O arquivo do projeto publica a porta 9000 sem limite de endereço e já limita o PostgreSQL ao endereço local. Tratado da mesma forma, o Listmonk só é acessado pelo proxy reverso.
• O nome de host: o arquivo aconselha um nome de domínio completo.

Inicie em seguida os serviços, criando de antemão a conta Super Admin. Essas duas variáveis só servem na primeira execução, e sem elas a conta é criada na primeira visita à interface: melhor que ela exista antes de abrir seu domínio.

LISTMONK_ADMIN_USER=votre-identifiant LISTMONK_ADMIN_PASSWORD=votre-mot-de-passe docker compose up -d

Sem Docker: o binário

O Listmonk também roda como programa isolado, ao lado de seu próprio servidor PostgreSQL, na versão 12 ou mais recente, com o banco já criado.

1. Baixe o arquivo da v6.2.0 na página de versões do projeto, por exemplo listmonk_6.2.0_linux_amd64.tar.gz, evitando a beta exibida no topo, e extraia o binário.
2. Gere o arquivo de configuração e preencha os acessos ao banco no config.toml.
3. Instale as tabelas e inicie o Listmonk.

./listmonk --new-config
./listmonk --install
./listmonk

Por padrão, o config.toml escuta em localhost:9000, o que serve atrás de um proxy reverso. O repositório fornece um arquivo de serviço listmonk@.service para o systemd.

O tamanho do servidor

O site do projeto cita uma instância de produção que envia uma campanha de mais de 7 milhões de e-mails com uma fração de um núcleo de processador e um pico de 57 MB de memória. Ele não publica mínimo nem número para o PostgreSQL, cujo volume cresce com seus assinantes, suas aberturas e seus cliques. Em um VPS gerenciado, descreva-nos o uso e recomendamos o tamanho adequado.

HTTPS e o proxy reverso

Seus assinantes clicam em links que apontam para sua instância: descadastro, confirmação, rastreamento de cliques. Ela é servida, portanto, em HTTPS e em um nome de domínio próprio. Crie os registros A e AAAA desse nome apontando para seu servidor, onde os visitantes chegam pelas portas 80 e 443. A documentação do Listmonk deixa a escolha do proxy; estas são duas configurações comuns.

Com o Caddy

O Caddy obtém e renova sozinho o certificado:

listmonk.example.com {
    reverse_proxy 127.0.0.1:9000
}

Com o Nginx e o Certbot

Por padrão, o Nginx recusa requisições com mais de 1 MB, com um erro 413. Para importar um arquivo de assinantes ou imagens, aumente esse limite conforme o tamanho de seus arquivos:

server {
    listen 80;
    listen [::]:80;
    server_name listmonk.example.com;
    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Em seguida, o Certbot instala o certificado Let's Encrypt e o redirecionamento para HTTPS, e depois renova o certificado por conta própria:

sudo certbot --nginx -d listmonk.example.com

As primeiras configurações

Conecte-se em https://listmonk.example.com/admin e abra “Settings”:

• “General”, “Root URL”: o endereço público de sua instância, sem barra final, como https://listmonk.example.com. O Listmonk tira dele os links de descadastro, de confirmação e de rastreamento de seus e-mails. O valor inicial, http://localhost:9000, não funcionaria para seus assinantes.
• “General”, “Default from email”: o endereço de remetente padrão, em seu domínio, no lugar do exemplo fornecido.
• “Media”, “Upload path”: /listmonk/uploads, a pasta que o arquivo Compose monta no servidor.
• “General”: a página pública de inscrição e o arquivo público estão ativos de início. Mantenha-os se você precisar deles.
• “Security”, “Enable CAPTCHA”: desativado de início, ele protege o formulário público de inscrição.

O que fica público, o que pode ser fechado

Para filtrar o acesso, por endereço IP ou por um proxy de autenticação, a documentação divide assim as rotas:

O envio: o Listmonk passa por seus servidores SMTP

O Listmonk prepara e cadencia seus e-mails e depois os entrega aos servidores SMTP que você declarar em “Settings”, “SMTP”. Ele não os entrega por conta própria às caixas de seus assinantes: a qualidade da entrega depende, portanto, desse servidor, de seu domínio e de suas listas.

Para um envio em volume, escolha um serviço de envio especializado: ele carrega a reputação de seus envios e as assinaturas de seu domínio, e sabe devolver os bounces. A partir de um VPS Simafri, o envio passa por um relay SMTP autenticado, na porta 587: aqui, o desse serviço.

Para se orientar, a documentação do Listmonk descreve os bounces do Amazon SES, do Azure Communication Services, do SendGrid, do Postmark, do Forward Email e do Lettermint. Compare-os conforme seu volume e seus destinatários.

Clique então em “Test connection”: o Listmonk envia uma mensagem de teste e mostra o erro do servidor se o envio falhar. Você pode declarar vários servidores, escolher um deles por campanha ou direcionar os envios conforme o endereço ou o domínio do remetente.

A vazão

Ajuste-a em “Settings”, “Performance”, abaixo do limite de seu serviço:

• “Concurrency” e “Message rate”: o número de threads de envio e de mensagens por segundo para cada uma. Os valores iniciais, 10 e 10, autorizam até 100 mensagens por segundo.
• “Batch size”: o número de assinantes lidos no banco a cada passagem, 1.000 de início, a manter acima da vazão visada. Mais alto, consome mais memória.
• “Enable sliding window limit”: um teto de mensagens em um intervalo de tempo, útil quando seu serviço conta por hora.
• “Maximum error threshold”: o número de erros a partir do qual uma campanha é pausada.

Uma mensagem que falha é repetida conforme a configuração “Retries”, em outras conexões do servidor. Se falhar de novo, o Listmonk a registra como erro e passa à seguinte: acompanhe esses erros durante uma campanha grande.

Entregabilidade, descadastro e consentimento

Hospedar a aplicação deixa esses assuntos em suas mãos, e são eles que decidem se seus e-mails chegam.

SPF, DKIM e DMARC

Envie a partir de um endereço de seu domínio e publique na zona DNS dele os registros SPF e DKIM que seu serviço de envio fornecer, com um registro DMARC. O Google exige os três de quem envia mais de 5.000 mensagens por dia para contas Gmail, com um domínio de envio alinhado ao SPF ou ao DKIM, o descadastro com um clique para as mensagens de marketing e uma taxa de denúncias de spam abaixo de 0,30%, idealmente abaixo de 0,10%.

O descadastro

• Na mensagem: coloque {{ UnsubscribeURL }} no rodapé de seu modelo. Esse link leva ao gerenciamento de preferências e ao descadastro.
• Nos cabeçalhos: a opção “Include List-Unsubscribe header” de “Settings”, “Privacy”, ativa de início, permite que os programas de e-mail proponham o descadastro com um clique.
• Os dados: a mesma página de configurações deixa ao assinante o direito de exportar os dados dele, apagá-los e se colocar na lista de bloqueio. Essas opções estão ativas de início.

O consentimento de seus destinatários

O Listmonk aplica o tipo de lista que você escolher. Em uma lista em simple opt-in, um assinante adicionado sem confirmação recebe suas campanhas mesmo assim. Em uma lista em double opt-in, ele recebe primeiro um e-mail de confirmação, e só os assinantes confirmados recebem suas campanhas. É a escolha que melhor protege sua reputação de envio e que mantém um registro claro do consentimento.

As regras dependem do país de seus destinatários. Na França, por exemplo, a CNIL exige o consentimento prévio das pessoas físicas, por uma ação positiva, como uma caixa não pré-marcada, com uma exceção para seus clientes sobre produtos ou serviços semelhantes. Entre empresas, a prospecção pode se basear no interesse legítimo se disser respeito à atividade profissional delas. Em todos os casos, cada mensagem identifica o remetente e oferece um meio simples de recusar as seguintes.

Escreva somente a pessoas que esperam suas mensagens. Uma lista comprada ou antiga faz subir os bounces e as denúncias de spam, e é seu domínio que arca com as consequências.

O rastreamento de aberturas e de cliques

O pixel de rastreamento e o rastreamento de cliques tocam a privacidade, e a documentação pede para usá-los respeitando regras como o GDPR. Por padrão, esse rastreamento não é vinculado a cada assinante: a opção “Individual subscriber tracking” o vincula, e “Disable tracking” o desliga por completo, em “Settings”, “Privacy”.

Os bounces

Continuar escrevendo a um endereço que rejeita suas mensagens prejudica sua reputação de envio. O tratamento dos bounces vem desativado: ative-o em “Settings”, “Bounces” e escolha um destes dois caminhos.

• O webhook de seu serviço de envio: ative “Enable bounce webhooks” e a opção de seu serviço. O Listmonk recebe os bounces do SES, do Azure Communication Services, do SendGrid, do Postmark, do Forward Email e do Lettermint em um endereço como https://listmonk.example.com/webhooks/service/ses, com a última palavra mudando conforme o serviço. Esse endereço deve continuar público.
• Uma caixa POP3: o Listmonk relê uma caixa que recebe os bounces, a de seu endereço de remetente ou uma caixa dedicada. Ele deduz então o tipo de bounce pelo conteúdo da mensagem e considera leve o que não reconhece.

Para uma caixa dedicada, declare-a como endereço de retorno em “Settings”, “SMTP”, “Custom headers”:

[
  {"Return-Path": "your-bounce-inbox@example.com"}
]

As configurações iniciais são as que a documentação dá para o SES, e formam uma boa base:

PostgreSQL, a única dependência

O Listmonk exige PostgreSQL 12 ou mais recente. O arquivo Compose traz o postgres:17-alpine, com os dados no volume Docker listmonk-data. Assinantes, campanhas, modelos, estatísticas e a maioria das configurações vivem nele; só os acessos ao banco e o endereço de escuta ficam na configuração.

Para apontar para um servidor PostgreSQL existente, modifique as variáveis LISTMONK_db__host, LISTMONK_db__port, LISTMONK_db__user, LISTMONK_db__password e LISTMONK_db__database do serviço app.

O Listmonk foi concebido para listas grandes. À medida que o banco cresce, é ele que pode deixar a interface lenta: com milhões de assinantes, o painel e os contadores podem levar dezenas de segundos para aparecer. O projeto aconselha então dois gestos:

• “Cache slow database queries”, em “Settings”, “Performance”: os contadores são calculados em intervalo regular, toda noite às 3 h por padrão.
• VACUUM ANALYZE em um banco grande, por exemplo toda semana. O comando bloqueia as consultas durante a execução, em geral alguns segundos.

docker compose exec db psql -U listmonk -d listmonk -c 'VACUUM ANALYZE;'

Backups e atualizações

Dois elementos formam sua instância: o banco PostgreSQL e a pasta uploads, se suas imagens ficam no disco. O pg_dump produz uma exportação consistente sem parar o Listmonk nem bloquear os outros acessos ao banco:

docker compose exec -T db pg_dump -U listmonk listmonk > listmonk-$(date +%F).sql
tar -czf listmonk-uploads-$(date +%F).tar.gz uploads

Para restaurar, pare o Listmonk, esvazie o banco e recarregue a exportação. Como a documentação esclarece, esse gesto apaga o banco existente:

docker compose stop app
docker compose exec db psql -U listmonk -d listmonk -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
docker compose exec -T db psql -U listmonk -d listmonk < listmonk-2026-11-01.sql
docker compose start app

Atualizar

1. Leia as notas da nova versão: o Listmonk avisa sobre as novas versões na interface dele, e algumas trazem correções de segurança.
2. Exporte o banco, como o projeto pede antes de qualquer atualização.
3. Mude a tag da imagem no docker-compose.yml.
4. Execute os comandos da documentação. O arquivo Compose migra o banco na inicialização.

docker compose down app
docker compose pull
docker compose up app -d

Com o binário, pare o Listmonk, substitua o binário, execute ./listmonk --upgrade e reinicie-o. Para voltar a uma versão anterior, restaure a exportação feita antes da atualização e recoloque a tag antiga.

Quem faz o quê em um VPS gerenciado

A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Listmonk continua sendo seu software, com as configurações dele, suas listas e suas campanhas.

Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.