Troubleshooting
Use esta página para identificar a causa de um problema e as ações corretivas. Para rastrear o caminho completo de uma mensagem, veja a seção Usando o ledger ao final.
Comece pelo check de DNS. Antes de investigar entregabilidade (spam, DKIM=fail, SPF=fail), rode mxout check — ele valida DKIM/SPF/DMARC de cada domínio e aponta a causa automaticamente. Ver CLI — mxout check.
Erros na chamada ao /send
401 Unauthorized
| Sintoma | Causa provável | Ação |
|---|---|---|
API retorna 401 |
X-Auth-Token ausente ou incorreto |
Confirme que o header X-Auth-Token está presente e igual ao valor da variável de ambiente MXOUT_AUTH_TOKEN no servidor |
O token não fica em mxout.json. Ele vem exclusivamente da variável de ambiente. Verifique com:
docker exec mxout printenv MXOUT_AUTH_TOKEN400 — domínio não tem kit configurado
| Sintoma | Causa provável | Ação |
|---|---|---|
API retorna 400 com mensagem sobre domínio sem kit |
O domínio do remetente não está em domains no mxout.json, ou o serviço não foi reiniciado após a edição |
Adicione o domínio em mxout.json e reinicie o mxout |
Confirme que a entrada existe:
grep -A3 '"exemplo.com"' /etc/mxout/mxout.jsonDepois reinicie:
docker restart mxoutOutros casos que retornam 400: campo from ausente, endereço from malformado ou domínio do remetente sem entrada em domains.
413 — corpo muito grande
| Sintoma | Causa provável | Ação |
|---|---|---|
API retorna 413 |
O corpo da requisição ultrapassa 5 MiB | Reduza o tamanho do e-mail (texto ou anexos Base64). O mxout não aceita mensagens acima de 5 MiB |
Problemas de entrega
E-mail cai em spam ou DKIM=fail
| Sintoma | Causa provável | Ação |
|---|---|---|
DKIM: FAIL no "Mostrar original" do Gmail |
Registro TXT DKIM no DNS diverge da chave privada usada pelo mxout | Verifique se o valor p= no DNS corresponde à chave gerada pelo mxout-keygen. Se regenerou a chave, republique o registro DNS |
DKIM: FAIL mesmo com DNS correto |
key_path em mxout.json aponta para arquivo errado ou inacessível |
Confirme que o arquivo existe e é legível pelo processo do mxout |
| E-mail em spam sem falha de assinatura | PTR/rDNS ausente ou não corresponde ao helo_hostname |
Configure o PTR no painel do VPS para que o reverso do IP aponte para o mesmo valor de helo_hostname em mxout.json |
| E-mail em spam sem falha de assinatura | IP do servidor em blocklist | Verifique o IP em MXToolbox ou similar e solicite remoção |
SPF: FAIL |
IP do servidor não está no registro SPF do domínio | Adicione o IP ao registro SPF: v=spf1 ip4:<IP do servidor> -all |
Veja como publicar os registros corretos em Configurar DNS.
Falha de conexão — porta 25 bloqueada
| Sintoma | Causa provável | Ação |
|---|---|---|
Ledger mostra attempt seguido de failed com erro de conexão recusada ou timeout |
Provedor de VPS bloqueia a porta 25 de saída por padrão | Solicite ao provedor a liberação da porta 25 de saída (OVH, Hetzner e outros exigem solicitação explícita) |
Para testar se a porta está acessível:
nc -zv <IP do servidor MX de destino> 25Se a conexão falhar a partir do servidor mxout, o provedor está bloqueando a porta.
Usando o ledger
O ledger é a trilha de auditoria do mxout. Cada evento de uma mensagem é registrado como uma linha JSON no stdout, correlacionado pelo campo message_id.
Para acompanhar o que aconteceu com uma mensagem específica, filtre os logs pelo message_id retornado na resposta do /send:
docker logs mxout 2>/dev/null | grep '"message_id":"<ID>"'Os eventos em ordem típica de entrega bem-sucedida:
received → mensagem aceita pelo /send
signed → assinatura DKIM aplicada
mx_resolved → registro MX do domínio de destino resolvido
attempt → tentativa de conexão SMTP iniciada
delivered → servidor de destino aceitou a mensagem (2xx)Se a entrega falhar, os eventos possíveis são:
deferred → falha temporária (4xx ou erro de conexão), mxout vai retentar
failed → falha permanente (5xx) ou tentativas esgotadas, mensagem descartadaO mxout tenta imediatamente, depois após 5s e 10s e 30s. Após esgotar as tentativas, descarta a mensagem (stateless — nada persiste em disco).
Veja a referência completa dos campos em Ledger.
Para perguntas sobre comportamento esperado do mxout, consulte o FAQ.