2026: O que fazer quando os e-mails de teste não aparecem no Mailpit 1.33.1?

Diagnóstico do resultado ausente

“Envio concluído” pode descrever resultados diferentes. O teste pode ter verificado que uma função foi chamada, que a aplicação entregou uma mensagem ao servidor SMTP, ou que o Mailpit armazenou a mensagem. Essas evidências não são intercambiáveis.

Um cenário comum: um teste automatizado verifica que o método de envio foi acionado e termina como aprovado. Porém, o processo da aplicação aponta para outro host, ou a consulta posterior busca o destinatário errado. O teste passou segundo a própria asserção, mas isso não demonstra que a mensagem entrou na instância que você está observando.

Separe as etapas antes de alterar código:

O Mailpit mostra envio bem-sucedido na aplicação, mas não há mensagem na caixa: por onde começar? Compare o host, a porta e o ambiente registrados pela aplicação com os da instância aberta no navegador. Depois, confira a resposta de envio e o destinatário final. Não use apenas o log “função chamada” como prova de recebimento.

Destino SMTP e ambiente em execução

A primeira investigação é descobrir para onde a aplicação realmente envia. Em desenvolvimento local, staging e contêineres, nomes de host semelhantes podem apontar para destinos diferentes. localhost dentro de um contêiner normalmente identifica o próprio contêiner, não automaticamente o computador host nem outro serviço da rede.

O Mailpit documenta a configuração de SMTP separadamente da configuração da interface HTTP. Consulte a documentação oficial de configuração SMTP e a documentação da interface e do servidor HTTP. Os valores padrão documentados são a porta 1025 para SMTP e a porta 8025 para a interface web; configurações locais podem substituí-los. Confirme os valores da sua instância antes de usar esses números como referência.

Faça a verificação no processo que realmente envia a mensagem, não apenas no arquivo de configuração que você espera que ele leia. Variáveis de ambiente, configurações específicas de execução e arquivos de teste podem substituir os valores locais. Registre, sem expor credenciais, o host, a porta e o ambiente usados no momento do envio.

O teste envia por SMTP ou por outro caminho? Não presuma que toda integração usa SMTP. A documentação de envio de mensagens do Mailpit descreve os caminhos de envio disponíveis. Identifique o método efetivamente adotado pela sua aplicação e confira o destino correspondente. Se o envio for feito por HTTP, validar apenas o SMTP não localiza a causa.

Guarde a resposta de envio e o erro completo da aplicação, se houver. Não invente uma interpretação para um código de resposta que você não confirmou na documentação do método usado. O dado decisivo é se a submissão chegou ao serviço correto e qual resposta esse serviço devolveu.

Parsing e mudanças da versão

Na versão 1.33.1, o registro oficial menciona alterações em parsing de cabeçalhos, tratamento de destinatários Bcc e rejeição de mensagens que não podem ser interpretadas. Isso torna a versão relevante quando o defeito aparece apenas com uma mensagem específica. Não significa, porém, que essas mudanças expliquem todo e-mail ausente.

O caminho seguro é salvar uma amostra mínima que reproduza o problema e a resposta observada pelo remetente. Compare uma mensagem simples com outra que contenha o nome de exibição não ASCII ou Bcc que participa do caso. Depois, confira a versão realmente em execução — a versão do arquivo de configuração ou da imagem planejada não prova qual processo está ativo.

Como saber se o problema é parsing no Mailpit 1.33.1? Procure evidência específica: o envio alcança a instância correta, mas uma amostra reproduzível com determinados cabeçalhos não é aceita ou não aparece como esperado. A versão 1.33.1 documenta a rejeição de mensagens impossíveis de interpretar; portanto, não trate a ausência como descarte silencioso sem verificar a resposta do serviço e a amostra. A documentação de integração ajuda a construir testes controlados, mas não substitui a reprodução com a mensagem real da sua aplicação.

Ao compartilhar uma amostra, remova dados pessoais, tokens, códigos válidos e conteúdo de usuários. Para organizar essa higiene de dados, consulte o aviso de dados do Tmpkey. Isso é especialmente importante em ambientes de staging que reproduzem mensagens parecidas com as de produção.

Consulta da interface e da API

Se a mensagem está visível na interface, a etapa de envio até aquela instância funcionou. Se o teste ainda afirma que ela não existe, investigue a consulta: destinatário, remetente, termos de busca, intervalo considerado pela lógica do teste e identificador usado para abrir ou recuperar a mensagem.

A interface e a API também podem estar apontando para instâncias diferentes. Confira as URLs configuradas por cada componente. Em seguida, pesquise na interface pelo endereço exato do destinatário e pelo assunto exclusivo desta execução. Evite depender de uma busca genérica que possa corresponder a mensagens antigas.

A API do Mailpit não encontra uma mensagem recém-enviada: o que verificar? Primeiro confirme na interface se a mensagem está armazenada. Se estiver, compare os filtros do código com os cabeçalhos e o destinatário que aparecem na mensagem. Depois, confira se o teste está usando o endpoint e o formato de identificador documentados para a API disponível na sua versão. A documentação oficial da API é a referência para parâmetros e formas de consulta; não presuma que qualquer valor retornado pode ser usado como identificador em outro endpoint.

Quando o teste busca “a mensagem mais recente”, há risco de associar o resultado a outro envio concorrente ou a uma execução anterior. Uma prática mais robusta é incluir um identificador único da execução em um campo previsível, como o assunto ou um cabeçalho próprio, e usar esse valor para localizar a mensagem. Isso reduz ambiguidade sem depender de um tempo de espera fixo. Se não puder alterar a mensagem, isole a execução de teste e registre os critérios exatos da busca.

Reexecução e limite de aceitação

Depois de corrigir o destino, o parsing ou a consulta, repita o teste que falhou e uma mensagem simples de controle. Não encerre a análise apenas porque um novo envio apareceu: confira se a mensagem pertence à execução atual, se o destinatário corresponde ao esperado e se o conteúdo necessário foi interpretado corretamente.

Use esta lista antes de marcar a integração como aprovada:

• [ ] Confirme a versão do processo Mailpit realmente ativo e compare-a com o registro oficial da versão.
• [ ] Registre host, porta e método de envio usados pela aplicação no ambiente sob teste.
• [ ] Verifique a resposta do envio e os logs correspondentes; diferencie chamada de função de submissão aceita.
• [ ] Procure na interface a mensagem com destinatário e identificador próprios desta execução.
• [ ] Se a interface exibir a mensagem, valide a mesma instância, o endpoint e os filtros usados pela API.
• [ ] Execute novamente o caso simples e o caso com o cabeçalho ou destinatário que reproduzia o defeito.
• [ ] Remova dados pessoais, segredos e códigos válidos dos registros compartilhados.
• [ ] Documente o alcance do teste: captura local, parsing e consulta; não entrega em provedor externo.

A conclusão precisa corresponder à evidência. Se a mensagem aparece no Mailpit, você demonstrou que a aplicação conseguiu enviar até aquele coletor local e que ele armazenou a mensagem. Você ainda não demonstrou que um provedor externo aceitou o e-mail, que ele chegou à caixa de entrada ou que não foi classificado como spam.

Para testar a entrega externa, faça uma verificação separada em uma caixa controlada e autorizada. Avalie também SPF, DKIM, DMARC, rejeições do provedor e classificação da mensagem. O Mailpit é útil para inspecionar o percurso local; ele não substitui um teste de entrega real.

Endereço de teste e escolha do coletor

Para validar o produto que você mantém, escolha o tipo de endereço de acordo com o que precisa provar. Uma caixa local como o Mailpit favorece inspeção reproduzível de mensagens e integração com testes. Uma caixa temporária separada pode ajudar a receber mensagens em um endereço que não seja o seu endereço principal. Um alias ou endereço de teste dedicado pode ser melhor quando você precisa manter o histórico ou responder mensagens.

O custo oculto de usar o endereço pessoal em testes não é apenas o volume de mensagens. Você também pode misturar dados de produção e staging, expor informações pessoais em logs e dificultar a limpeza de contas criadas para QA. Por outro lado, uma caixa temporária não é a escolha certa se o fluxo exige recuperação de conta no futuro, histórico duradouro ou resposta por e-mail.

Se você quiser avaliar um endereço temporário como destino de um teste controlado, consulte o Tmpkey e confirme diretamente na página quais recursos estão disponíveis para o seu caso. Não presuma retenção, encaminhamento, personalização, necessidade de cadastro ou compatibilidade com qualquer fluxo sem verificar essas condições. O uso deve continuar restrito ao teste do seu próprio produto ou a um ambiente autorizado.

Para contas bancárias, pagamentos, serviços públicos e qualquer conta importante que precise de recuperação posterior, use um endereço duradouro sob seu controle. Para uma rodada pontual de cadastro, um código de verificação ou uma notificação de staging, um coletor local ou um endereço temporário pode reduzir a exposição do endereço principal. A decisão técnica é a mesma do diagnóstico: escolha o destino que fornece a evidência de que você precisa, sem atribuir a ele uma prova que não pode oferecer.