Alojar Listmonk num VPS gerido: as suas newsletters no seu servidor

O que faz o Listmonk

O Listmonk gere as suas listas de difusão e as suas newsletters a partir de uma interface web. É um programa único, escrito em Go, cuja única dependência é o PostgreSQL. As suas listas são de sentido único: escreve aos seus subscritores, 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 subscritores, e uma segmentação por expressões SQL sobre os seus atributos.
• As campanhas: um editor visual de arrastar e largar, um editor WYSIWYG, Markdown, HTML ou texto simples, e modelos em linguagem Go com mais de 100 funções.
• As estatísticas: aberturas, cliques, rejeições e ligações mais seguidas, campanha a campanha.
• As mensagens transacionais: uma API para enviar uma mensagem a partir de um modelo, por exemplo uma confirmação de encomenda. Os «messengers» em webhook HTTP abrem também o SMS ou o WhatsApp, a ligar ao serviço da sua escolha.
• Os subscritores: uma página onde cada um gere as suas preferências, exporta os seus dados ou os apaga.
• A equipa: funções e permissões precisas, a autenticação única OIDC e tokens de API limitados.
• Os ficheiros multimédia: uma biblioteca de imagens no disco ou num armazenamento compatível com S3.

O que permite a licença AGPL-3.0

O Listmonk é publicado sob a licença GNU AGPL versão 3. Pode utilizá-lo, inclusive numa empresa, e enviar as suas campanhas como as dos seus clientes, sem licença para comprar. Resta o custo do servidor e o do seu serviço de envio.

O artigo 13 acrescenta uma condição própria da AGPL: se modificar o programa, a sua versão tem de propor claramente a todos os que a utilizam à distância, pela rede, a obtenção do respetivo código-fonte, gratuitamente. Se distribuir cópias, aplicam-se também as obrigações de partilha do código da licença. Fazer correr o Listmonk sem o modificar não desencadeia este artigo.

Que 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 sobre as permissões. A 11 de novembro de 2026, a imagem Docker latest designa esta v6.2.0.

A versão 7 substitui toda a interface de administração, muda alguns dos seus endereços, faz da definição app.from_email uma lista de endereços e modifica chaves de tradução, o que afeta os modelos personalizados. Leia as suas notas de versão antes de passar a ela.

O ficheiro Compose do projeto executa --upgrade --yes em cada arranque: uma nova imagem migra a base de dados sem lhe perguntar. Ora, uma base de dados migrada não se relê com uma versão mais antiga, e voltar atrás obriga a restaurar uma cópia de segurança. Com uma etiqueta fixa, como v6.2.0, a mudança de versão continua a ser uma decisão sua.

A instalação com o Docker Compose

O projeto recomenda o Docker Compose: o seu ficheiro arranca o Listmonk e o PostgreSQL em conjunto. Num servidor com o Docker instalado, crie uma pasta e obtenha esse ficheiro:

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

O projeto pede para adaptar este ficheiro ao seu ambiente. Eis as únicas linhas a mudar, o resto 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 palavra-passe da base de dados: o ficheiro fornece listmonk como valor de partida. Mude-a antes do primeiro arranque, porque a imagem PostgreSQL só lê esta variável numa pasta de dados vazia.
• A imagem: uma versão precisa em vez de latest, pela razão vista acima.
• A porta publicada em 127.0.0.1: é a nossa adaptação. O ficheiro do projeto publica a porta 9000 sem limite de endereço, e limita já o PostgreSQL ao endereço local. Tratado da mesma forma, o Listmonk só é acessível através do proxy inverso.
• O nome de anfitrião: o ficheiro aconselha um nome de domínio completo.

Arranque depois os serviços, criando antecipadamente a conta Super Admin. Estas duas variáveis só servem para o primeiro arranque, e sem elas a conta cria-se na primeira visita à interface: mais vale que exista antes de abrir o 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 corre também como programa isolado, ao lado do seu próprio servidor PostgreSQL, na versão 12 ou superior, onde a base de dados já esteja criada.

1. Descarregue o arquivo da v6.2.0 na página das versões do projeto, por exemplo listmonk_6.2.0_linux_amd64.tar.gz, evitando a beta apresentada em primeiro lugar, e extraia o binário.
2. Gere o ficheiro de configuração e preencha depois os acessos à base de dados em config.toml.
3. Instale as tabelas e depois arranque o Listmonk.

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

Por predefinição, o config.toml escuta em localhost:9000, o que convém atrás de um proxy inverso. O repositório fornece um ficheiro 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. Não publica nem mínimo nem número para o PostgreSQL, cujo volume cresce com os seus subscritores, as suas aberturas e os seus cliques. Num VPS gerido, descreva-nos a sua utilização e recomendamos-lhe o tamanho adequado.

HTTPS e o proxy inverso

Os seus subscritores clicam em ligações que apontam para a sua instância: cancelamento da subscrição, confirmação, acompanhamento dos cliques. Serve-se, por isso, em HTTPS no seu próprio nome de domínio. Crie os registos A e AAAA desse nome para o seu servidor, onde os visitantes chegam pelas portas 80 e 443. A documentação do Listmonk deixa a escolha do proxy; eis duas configurações correntes.

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

O Nginx recusa por predefinição os pedidos de mais de 1 MB, com um erro 413. Para importar um ficheiro de subscritores ou imagens, aumente este limite à medida dos seus ficheiros:

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;
    }
}

O Certbot instala depois o certificado Let’s Encrypt e o redirecionamento para HTTPS, e renova o certificado por si próprio:

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

As primeiras definições

Inicie sessão em https://listmonk.example.com/admin e abra «Settings»:

• «General», «Root URL»: o endereço público da sua instância, sem barra final, como https://listmonk.example.com. O Listmonk tira daí as ligações de cancelamento, de confirmação e de acompanhamento dos seus e-mails. O seu valor de partida, http://localhost:9000, não funcionaria junto dos seus subscritores.
• «General», «Default from email»: o endereço de expedição predefinido, no seu domínio, em vez do exemplo fornecido.
• «Media», «Upload path»: /listmonk/uploads, a pasta que o ficheiro Compose monta no servidor.
• «General»: a página pública de subscrição e o arquivo público estão ativos de início. Mantenha-os se precisar deles.
• «Security», «Enable CAPTCHA»: desativado de início, protege o formulário público de subscrição.

O que fica público, o que pode fechar-se

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

O envio: o Listmonk passa pelos seus servidores SMTP

O Listmonk prepara e cadencia os seus e-mails e confia-os depois aos servidores SMTP que declarar em «Settings», «SMTP». Não os entrega ele próprio nas caixas de correio dos seus subscritores: a qualidade da entrega depende, portanto, desse servidor, do seu domínio e das suas listas.

Para um envio em volume, escolha um serviço de envio especializado: assume a reputação dos seus envios e as assinaturas do seu domínio, e sabe reportar as rejeições. A partir de um VPS Simafri, o envio passa por uma retransmissão SMTP autenticada, na porta 587: aqui, a desse serviço.

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

Clique depois em «Test connection»: o Listmonk envia uma mensagem de teste e mostra o erro do servidor se o envio falhar. Pode declarar vários servidores, escolher um deles por campanha, ou encaminhar os envios consoante o endereço ou o domínio de expedição.

O débito

Defina-o em «Settings», «Performance», abaixo do limite do seu serviço:

• «Concurrency» e «Message rate»: o número de fios de envio e de mensagens por segundo para cada um. Os valores de partida, 10 e 10, autorizam até 100 mensagens por segundo.
• «Batch size»: o número de subscritores lidos na base de dados em cada passagem, 1000 de início, a manter acima do débito pretendido. Mais alto, consome mais memória.
• «Enable sliding window limit»: um limite de mensagens numa duração, útil quando o seu serviço conta à hora.
• «Maximum error threshold»: o número de erros a partir do qual uma campanha é posta em pausa.

Uma mensagem que falha é repetida segundo a definição «Retries», noutras ligações do servidor. Se falhar de novo, o Listmonk regista-a como erro e passa à seguinte: vigie estes erros durante uma campanha grande.

Entregabilidade, cancelamento da subscrição e consentimento

Alojar a aplicação deixa-o senhor destes assuntos, e são eles que decidem se os seus e-mails chegam.

SPF, DKIM e DMARC

Envie a partir de um endereço do seu domínio e publique na respetiva zona DNS os registos SPF e DKIM que o seu serviço de envio lhe dá, com um registo DMARC. A Google pede os três aos remetentes de mais de 5000 mensagens por dia para contas Gmail, com um domínio de expedição alinhado com o SPF ou o DKIM, o cancelamento da subscrição com um clique para as mensagens de marketing e uma taxa de denúncia de spam abaixo de 0,30 %, idealmente abaixo de 0,10 %.

O cancelamento da subscrição

• Na mensagem: coloque {{ UnsubscribeURL }} no rodapé do seu modelo. Esta ligação leva à gestão das preferências e ao cancelamento da subscrição.
• Nos cabeçalhos: a opção «Include List-Unsubscribe header» de «Settings», «Privacy», ativa de início, permite aos programas de correio propor o cancelamento da subscrição com um clique.
• Os dados: a mesma página de definições deixa ao subscritor o direito de exportar os seus dados, de os apagar e de se pôr em lista de bloqueio. Estas opções estão ativas de início.

O consentimento dos seus destinatários

O Listmonk aplica o tipo de lista que escolher. Numa lista em simple opt-in, um subscritor adicionado sem confirmação recebe na mesma as suas campanhas. Numa lista em double opt-in, recebe primeiro um e-mail de confirmação, e só os subscritores confirmados recebem as suas campanhas. É a escolha que melhor protege a sua reputação de envio e que guarda um rasto claro do acordo.

As regras dependem do país dos seus destinatários. Em França, por exemplo, a CNIL pede o consentimento prévio dos particulares, por uma ação positiva como uma caixa não pré-marcada, com uma exceção para os seus clientes sobre produtos ou serviços semelhantes. Entre profissionais, a prospeção pode assentar no interesse legítimo se disser respeito à sua profissão. Em todos os casos, cada mensagem identifica o remetente e oferece um meio simples de recusar as seguintes.

Escreva apenas a pessoas que esperam as suas mensagens. Uma lista comprada ou antiga faz subir as rejeições e as denúncias de spam, e é o seu domínio que suporta as consequências.

O acompanhamento das aberturas e dos cliques

O pixel de acompanhamento e o acompanhamento dos cliques tocam na vida privada, e a documentação pede para os utilizar no respeito de regras como o RGPD. Por predefinição, este acompanhamento não está ligado a cada subscritor: a opção «Individual subscriber tracking» liga-o, e «Disable tracking» corta-o por completo, em «Settings», «Privacy».

As rejeições

Continuar a escrever a um endereço que rejeita as suas mensagens prejudica a sua reputação de envio. O tratamento das rejeições está desativado de início: ative-o em «Settings», «Bounces» e escolha depois um destes dois caminhos.

• O webhook do seu serviço de envio: ative «Enable bounce webhooks» e a opção do seu serviço. O Listmonk recebe as rejeições do SES, do Azure Communication Services, do SendGrid, do Postmark, do Forward Email e do Lettermint num endereço como https://listmonk.example.com/webhooks/service/ses, mudando a última palavra consoante o serviço. Este endereço deve manter-se público.
• Uma caixa POP3: o Listmonk relê uma caixa que recebe as rejeições, a do seu endereço de expedição ou uma caixa dedicada. Adivinha então o tipo de rejeição pelo conteúdo da mensagem e considera ligeiro 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 definições de partida são as que a documentação dá para o SES, e formam uma boa base:

PostgreSQL, a única dependência

O Listmonk exige o PostgreSQL 12 ou superior. O ficheiro Compose traz o postgres:17-alpine, com os seus dados no volume Docker listmonk-data. Subscritores, campanhas, modelos, estatísticas e a maior parte das definições vivem aí; só os acessos à base de dados 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 grandes listas. À medida que a base de dados cresce, é ela que pode abrandar a interface: com milhões de subscritores, o painel de controlo e os contadores podem demorar dezenas de segundos a aparecer. O projeto aconselha então dois gestos:

• «Cache slow database queries», em «Settings», «Performance»: os contadores calculam-se a intervalos regulares, todas as noites às 3 h por predefinição.
• VACUUM ANALYZE numa base de dados grande, por exemplo todas as semanas. O comando bloqueia os pedidos durante a sua passagem, em geral alguns segundos.

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

Cópias de segurança e atualizações

Dois elementos compõem a sua instância: a base de dados PostgreSQL e a pasta uploads, se as suas imagens ficarem no disco. O pg_dump produz uma exportação coerente sem parar o Listmonk nem bloquear os outros acessos à base de dados:

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 a base de dados e volte a carregar a exportação. Como a documentação esclarece, este gesto apaga a base de dados 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 assinala-lhe as novas versões na sua interface, e algumas trazem correções de segurança.
2. Exporte a base de dados, como o projeto pede antes de qualquer atualização.
3. Mude a etiqueta da imagem no docker-compose.yml.
4. Execute os comandos da documentação. O ficheiro Compose migra a base de dados no arranque.

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 volte a pôr a etiqueta antiga.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Listmonk continua a ser o seu software, com as suas definições, as suas listas e as suas campanhas.

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.