Postfix SMTP Relay

Sobre o projeto

O Postfix SMTP Relay é uma solução em português para configurar o Postfix como relay SMTP local para aplicações legadas.

A proposta é permitir que uma aplicação antiga envie e-mails para 127.0.0.1:25, enquanto o Postfix fica responsável por autenticação SMTP, STARTTLS/TLS, fila, logs, retry e encaminhamento para o servidor SMTP externo.

Essa abordagem é útil quando a aplicação não consegue negociar corretamente TLS moderno ou autenticação SMTP, mas ainda precisa enviar mensagens por uma infraestrutura de e-mail atual.

---

Índice

• Problema resolvido
• Como a solução funciona
• Arquitetura
• Funcionalidades
• Estrutura do projeto
• Instalação rápida
• Instalação com variáveis
• Configuração na aplicação
• Testes disponíveis
• Validação completa
• Interface web local
• Relatório técnico
• Troubleshooting rápido
• Segurança
• Documentação
• Roadmap
• Autor
• Licença

---

Problema resolvido

Aplicações legadas podem falhar ao enviar e-mails diretamente para servidores SMTP modernos que exigem:

• SMTP AUTH;
• STARTTLS;
• TLS 1.2 ou superior;
• remetente autorizado;
• políticas mais rígidas contra relay aberto.

Erros comuns:

535 Authentication Failed
554 Relaying Denied
SSLHandshakeException
Connection timed out

Com esta solução, a aplicação deixa de negociar TLS diretamente. O Postfix assume essa responsabilidade.

---

Como a solução funciona

A aplicação passa a enviar e-mails localmente:

127.0.0.1:25

O Postfix recebe essa mensagem local e encaminha para o SMTP externo com:

• autenticação SMTP;
• STARTTLS/TLS;
• controle de fila;
• retry automático;
• logs detalhados.

---

Arquitetura

Antes

flowchart LR
    A[Aplicação legada] -->|SMTP direto| B[Servidor SMTP externo]
    B --> C[Destinatários]

Loading

Depois

flowchart LR
    A[Aplicação legada] -->|SMTP local<br>127.0.0.1:25| B[Postfix Relay Local]
    B -->|SMTP AUTH<br>STARTTLS/TLS 1.2| C[Servidor SMTP externo]
    C --> D[Destinatários]

Loading

Fluxo técnico

sequenceDiagram
    participant APP as Aplicação
    participant PF as Postfix local
    participant SMTP as SMTP externo
    participant DST as Destinatário

    APP->>PF: Envia mensagem via 127.0.0.1:25
    PF->>PF: Enfileira mensagem
    PF->>SMTP: Conecta no SMTP externo
    PF->>SMTP: STARTTLS/TLS
    SMTP-->>PF: TLS estabelecido
    PF->>SMTP: Autentica via SASL
    SMTP-->>PF: Autenticação aceita
    PF->>SMTP: Envia mensagem
    SMTP-->>PF: 250 Message accepted
    SMTP->>DST: Entrega ao destinatário

Loading

---

Funcionalidades

• Configuração do Postfix como relay SMTP local.
• Suporte a STARTTLS.
• Suporte a TLS 1.2.
• SMTP AUTH via SASL.
• Instalador em Bash.
• Backup antes de alterar configurações.
• Script de rollback.
• Scripts de teste.
• Validação completa em um único comando.
• Interface web local para validação.
• Relatório técnico local.
• GitHub Actions para validação de Shell.
• ShellCheck.
• Verificação básica contra dados sensíveis.
• Documentação em português.
• Playbook Ansible.
• Dockerfile para laboratório.
• GitHub Pages.
• Exemplos por stack de aplicação.

---

Estrutura do projeto

.
├── README.md
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── ROADMAP.md
├── instalador
│   ├── instalar-postfix-relay.sh
│   ├── rollback.sh
│   └── validar-instalacao.sh
├── documentacao
│   ├── 01-visao-geral.md
│   ├── 02-arquitetura.md
│   ├── 03-instalacao.md
│   ├── 04-configuracao.md
│   ├── 05-validacao.md
│   ├── 06-testes.md
│   ├── 07-troubleshooting.md
│   ├── 08-seguranca.md
│   ├── 09-faq.md
│   ├── 10-roadmap.md
│   └── 11-interface-web.md
├── exemplos
├── testes
│   ├── testar-conectividade.sh
│   ├── testar-dns.sh
│   ├── testar-fila.sh
│   ├── testar-openssl.sh
│   ├── testar-postfix.sh
│   ├── testar-swaks.sh
│   └── testar-tudo.sh
├── scripts
│   └── gerar-relatorio.sh
├── web
│   ├── app.py
│   ├── requirements.txt
│   ├── static
│   └── templates
└── .github
    └── workflows
        └── ci.yml

---

Instalação rápida

git clone git@github.com:otaviox3/postfix-smtp-relay.git
cd postfix-smtp-relay

chmod +x instalador/*.sh testes/*.sh scripts/*.sh
sudo ./instalador/instalar-postfix-relay.sh

---

Instalação com variáveis

sudo SMTP_HOST="smtp.exemplo.com" \
SMTP_PORT="25" \
TLS_MODE="starttls" \
TLS_PROTOCOL="TLSv1.2" \
SMTP_USER="naoresponda@exemplo.com" \
SMTP_PASS="SENHA_AQUI" \
MAIL_FROM="naoresponda@exemplo.com" \
TEST_TO="destino@exemplo.com" \
RUN_SEND_TEST="yes" \
./instalador/instalar-postfix-relay.sh

---

Configuração na aplicação

Após instalar o relay local, configure a aplicação assim:

Host SMTP: 127.0.0.1
Porta SMTP: 25
SSL: desabilitado
STARTTLS: desabilitado
Autenticação SMTP: desabilitada
Remetente: e-mail autorizado no SMTP externo

Important

A aplicação não deve autenticar no Postfix local. Quem autentica no SMTP externo é o Postfix.

---

Testes disponíveis

DNS

SMTP_HOST="smtp.exemplo.com" ./testes/testar-dns.sh

Conectividade

SMTP_HOST="smtp.exemplo.com" SMTP_PORT="25" ./testes/testar-conectividade.sh

TLS

SMTP_HOST="smtp.exemplo.com" SMTP_PORT="25" TLS_MODE="starttls" ./testes/testar-openssl.sh

SMTP AUTH com Swaks

SMTP_HOST="smtp.exemplo.com" \
SMTP_PORT="25" \
SMTP_USER="naoresponda@exemplo.com" \
SMTP_PASS="SENHA_AQUI" \
MAIL_FROM="naoresponda@exemplo.com" \
TEST_TO="destino@exemplo.com" \
./testes/testar-swaks.sh

Postfix local

MAIL_FROM="naoresponda@exemplo.com" \
TEST_TO="destino@exemplo.com" \
./testes/testar-postfix.sh

Fila

./testes/testar-fila.sh

---

Validação completa

Execute todos os testes básicos:

SMTP_HOST="smtp.exemplo.com" \
SMTP_PORT="25" \
TLS_MODE="starttls" \
MAIL_FROM="naoresponda@exemplo.com" \
TEST_TO="destino@exemplo.com" \
./testes/testar-tudo.sh

---

Interface web local

Visual da interface

Uma das funcionalidades atuais do projeto é a interface web local para validação operacional.

cd web
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

Acesse:

http://127.0.0.1:8080

A interface permite:

• validar DNS;
• validar conectividade;
• validar TLS;
• consultar fila;
• visualizar últimos logs do Postfix.

Warning

A interface web deve ser usada localmente ou por túnel SSH. Não exponha diretamente na internet.

---

Relatório técnico

O projeto também possui geração de relatório local para apoio às validações e troubleshooting.

./scripts/gerar-relatorio.sh

O relatório inclui:

• informações do host;
• status do Postfix;
• configuração ativa;
• fila;
• últimos logs.

---

Troubleshooting rápido

535 Authentication Failed

Verifique usuário, senha, permissão de SMTP AUTH e entrada no sasl_passwd.

554 Relaying Denied

Verifique se o Postfix autenticou corretamente e se a porta do relayhost corresponde à entrada do sasl_passwd.

Connection timed out

Verifique DNS, firewall, ACL, rota e liberação da porta SMTP.

Different sender identity is not allowed

Verifique se o remetente usado pela aplicação é o mesmo autorizado no servidor SMTP externo.

---

Segurança

Nunca suba credenciais reais para o GitHub.

Arquivos sensíveis:

/etc/postfix/sasl_passwd
/etc/postfix/sasl_passwd.db
.env
*.secret
__pycache__/
*.pyc

Use exemplos genéricos:

smtp.exemplo.com
naoresponda@exemplo.com
SENHA_AQUI

---

Documentação

• Visão geral
• Arquitetura
• Instalação
• Configuração
• Validação
• Testes
• Troubleshooting
• Segurança
• FAQ
• Roadmap
• Interface web

---

Roadmap

• Instalador interativo.
• Documentação em português.
• GitHub Actions.
• Script de rollback.
• Validação completa.
• Interface web local.
• Relatório técnico.
• Exemplos por aplicação.
• Playbook Ansible.
• Dockerfile de laboratório.
• GitHub Pages.

---

Autor

Desenvolvido por Otávio Azevedo.

Projeto criado como estudo e documentação prática de uma solução de infraestrutura para compatibilizar aplicações legadas com servidores SMTP modernos.

---

Licença

Este projeto está licenciado sob a licença MIT.