Quando sua instância do Mastodon para de enviar e-mails para redefinição de senha, confirmações ou notificações, os usuários não conseguem concluir o registro ou recuperar contas. Esse problema geralmente decorre de configurações SMTP incorretas, bloqueios de firewall ou falhas de autenticação com seu provedor de e-mail. Este artigo explica as causas comuns de falhas na entrega de e-mail SMTP no Mastodon e fornece correções passo a passo para restaurar a funcionalidade de e-mail.
Principais Conclusões: Correção de Entrega de E-mail SMTP no Mastodon
- Variáveis de ambiente (.env.production): SMTP_HOST, SMTP_PORT, SMTP_LOGIN, SMTP_PASSWORD devem corresponder exatamente aos requisitos do seu provedor de e-mail.
- Reinicialização do Docker: Execute
docker-compose restart webapós alterar as configurações SMTP para aplicar as novas variáveis. - Firewall na porta 587 ou 465: O tráfego SMTP de saída deve ser permitido; teste com
telnet smtp.example.com 587a partir do servidor.
Por que a Entrega de E-mail SMTP do Mastodon Falha
O Mastodon usa a biblioteca Action Mailer do Ruby on Rails para enviar e-mails. O mailer lê as credenciais SMTP das variáveis de ambiente definidas no arquivo .env.production. Se alguma variável estiver ausente, com erro de digitação ou contiver um erro de digitação, o mailer não consegue autenticar com o servidor SMTP. Erros comuns incluem usar a porta 25, que muitos ISPs bloqueiam, esquecer de habilitar uma senha de aplicativo para serviços como Gmail ou Outlook, e definir o método de autenticação errado. Além disso, o servidor deve ter acesso de saída ao host SMTP na porta escolhida. Sem esse acesso, o Mastodon não consegue estabelecer uma conexão TCP, e a fila de e-mails fica cheia de tentativas de entrega com falha.
Passos para Corrigir a Entrega de E-mail SMTP do Mastodon
Siga estes passos em ordem. Teste após cada alteração importante para isolar o problema.
- Verifique as variáveis de ambiente SMTP no .env.production
Acesse seu servidor Mastodon via SSH e abra o arquivo.env.productioncom um editor de texto. Confirme se estas variáveis existem e estão corretas:SMTP_SERVER=smtp.example.comSMTP_PORT=587SMTP_LOGIN=seu_email@example.comSMTP_PASSWORD=sua_senha_de_aplicativoSMTP_FROM_ADDRESS=MastodonSMTP_AUTH_METHOD=plainSMTP_OPENSSL_VERIFY_MODE=peer
Se você usa STARTTLS, definaSMTP_ENABLE_STARTTLS_AUTO=true. Para conexões exclusivamente SSL na porta 465, definaSMTP_ENABLE_STARTTLS_AUTO=falseeSMTP_TLS=true. - Reinicie os serviços do Mastodon após editar o .env.production
Executedocker-compose restart webse usar Docker, ousystemctl restart mastodon-webpara uma configuração systemd. Isso recarrega as variáveis de ambiente nos processos em execução. - Teste a conectividade SMTP a partir do servidor
Use telnet para verificar a conectividade básica:telnet smtp.example.com 587. Se a conexão for bem-sucedida, você verá o banner SMTP. Se falhar, verifique suas regras de firewall para permitir tráfego de saída nas portas 587 ou 465. Verifique também se seu provedor de e-mail não bloqueia conexões do endereço IP do seu servidor. - Envie um e-mail de teste a partir do console do Mastodon
Abra o console Rails comdocker-compose run --rm web rails coucd /home/mastodon/live && RAILS_ENV=production bin/rails c. Execute:ActionMailer::Base.mail(from: "test@seudominio.com", to: "seu_email@example.com", subject: "Teste", body: "Teste").deliver_now
Se isso for bem-sucedido, a configuração SMTP está correta. Se gerar um erro, anote a mensagem de erro — ela geralmente aponta para problemas de autenticação ou conexão. - Verifique a fila de e-mails do Mastodon
Executedocker-compose run --rm web rails r "puts Sidekiq::Queue.new('mailers').size"para ver quantos e-mails estão na fila. Um número alto indica que tentativas de entrega anteriores falharam. Limpe a fila comdocker-compose run --rm web rails r "Sidekiq::Queue.new('mailers').clear"após corrigir as configurações SMTP.
Se a Entrega de E-mail do Mastodon Ainda Falhar Após a Correção Principal
“Net::SMTPAuthenticationError” ou “535 Authentication Failed”
Este erro significa que o servidor SMTP rejeitou as credenciais de login. Para Gmail, você deve usar uma Senha de Aplicativo em vez da senha normal da conta. Para Outlook.com, habilite a autenticação SMTP no centro de administração do Microsoft 365 e gere uma senha de aplicativo. Verifique também se o SMTP_LOGIN é o endereço de e-mail completo, não apenas o nome de usuário.
“Connection refused” ou “Connection timed out”
O servidor não consegue alcançar o host SMTP. Verifique se seu firewall permite conexões de saída na porta SMTP. Alguns provedores de hospedagem bloqueiam a porta 25 por padrão. Use as portas 587 ou 465. Confirme também se o hostname SMTP_SERVER resolve corretamente com nslookup smtp.example.com.
E-mails são enviados, mas vão para o spam
Configure registros DNS SPF e DKIM para seu domínio de envio. Adicione um registro TXT para SPF: v=spf1 include:_spf.google.com ~all para Gmail. Para DKIM, gere uma chave nas configurações do seu provedor de e-mail e adicione a chave pública como um registro TXT. Defina também o SMTP_FROM_ADDRESS para um domínio que corresponda ao domínio da sua instância Mastodon para melhorar a entregabilidade.
| Item | Porta 587 (STARTTLS) | Porta 465 (SSL/TLS) |
|---|---|---|
| Criptografia | Conexão simples que atualiza para TLS via STARTTLS | SSL/TLS desde o início |
| Variáveis de ambiente | SMTP_PORT=587, SMTP_ENABLE_STARTTLS_AUTO=true |
SMTP_PORT=465, SMTP_TLS=true, SMTP_ENABLE_STARTTLS_AUTO=false |
| Requisito de firewall | TCP de saída na porta 587 | TCP de saída na porta 465 |
| Provedores comuns | Gmail, Outlook.com, SendGrid | Amazon SES, Mailgun |
Após corrigir as configurações SMTP, sua instância do Mastodon poderá enviar e-mails de forma confiável. Monitore a fila de e-mails com o painel Sidekiq em /sidekiq na sua instância. Para instâncias de alto volume, considere usar um serviço de e-mail dedicado como SendGrid ou Amazon SES para evitar atingir limites de taxa de provedores de e-mail gratuitos.