O erro de e-mail não ASCII no Python 3.15.2 não significa que todo endereço internacionalizado falhará: primeiro identifique se a exceção acontece ao serializar o cabeçalho ou durante o envio, depois confira o suporte a SMTPUTF8 e valide o recebimento em uma caixa controlada. Essa orientação vale para testes de produtos próprios ou ambientes em que você tem autorização.
Este artigo é para quem desenvolve em Python 3.15.x e encontrou uma falha ao gerar cabeçalhos com endereços não ASCII.
Também ajuda profissionais de QA a testar geração, envio e recebimento de e-mails internacionalizados.
Quem mantém uma integração SMTP pode usá-lo para separar rejeição do servidor de falha na caixa de destino.
Última atualização: 1º de novembro de 2026. Dados conferidos na documentação oficial do Python 3.15, na página de lançamento do Python 3.15.2 e nas referências de email.policy e smtplib.
Python 3.15.2: o erro depende do endereço e da etapa
O ponto de partida é não tratar “e-mail não ASCII” como uma categoria única. Um nome de exibição com caracteres acentuados não é o mesmo que uma parte local internacionalizada, antes do símbolo @. E nenhum dos dois, por si só, informa se o servidor SMTP aceita a extensão necessária.
A documentação de novidades do Python 3.15 confirma uma fronteira específica: o gerador de e-mail pode lançar um erro quando não consegue achatar com precisão um cabeçalho de endereço que contém um endereço de e-mail não ASCII. Isso não equivale a dizer que qualquer texto não ASCII no corpo da mensagem é inválido, nem que todos os endereços internacionalizados são impossíveis de enviar. Consulte a descrição oficial do comportamento de geração de mensagens no Python 3.15.
A versão Python 3.15.2 foi publicada em 25 de outubro de 2026, conforme a página oficial do lançamento. Essa data identifica a versão, mas não prova, sozinha, qual código está em execução no ambiente nem qual dependência está produzindo a mensagem. Para investigar, registre a versão efetiva do interpretador e crie uma reprodução mínima com o mesmo tipo de endereço e a mesma política de mensagem usados pela aplicação.
Por que o Python 3.15 pode lançar um erro por causa de um endereço não ASCII?
A geração precisa converter a mensagem em uma representação serializada. Se o gerador não consegue produzir um cabeçalho de endereço correto nas condições da política aplicada, a falha pode surgir nessa conversão, antes de qualquer conexão SMTP. O diagnóstico, portanto, começa pela etapa em que a exceção acontece, não pela suposição de que o servidor recusou a mensagem.
Guarde a exceção completa e a saída produzida no ponto em que a aplicação falha. Um registro que mostre o texto inteiro da mensagem pode esconder a diferença entre um nome de exibição codificado e caracteres não ASCII no endereço propriamente dito. Para entender os limites do objeto de mensagem e sua serialização, consulte a documentação de email.message.
Atenção: sucesso ao construir um objeto EmailMessage não prova que o cabeçalho foi serializado corretamente. Da mesma forma, serialização bem-sucedida não prova que um servidor aceitou o envio ou que a mensagem chegou à caixa de destino.
Nome de exibição internacionalizado não é endereço internacionalizado
Considere separadamente estas duas partes:
- Nome de exibição: texto descritivo associado ao destinatário. Pode conter caracteres internacionais sem que a parte local do endereço tenha esses caracteres.
- Endereço: valor usado para endereçar a mensagem. Quando a parte local ou outro componente do endereço contém caracteres não ASCII, a aplicação entra em um cenário de endereço internacionalizado, ou EAI.
Essa distinção muda o diagnóstico. Se a mensagem usa um nome de exibição como “Equipe de suporte” com caracteres acentuados, mas o endereço permanece ASCII, verifique a representação do cabeçalho produzido e a codificação aplicada. Se o endereço em si contém caracteres não ASCII, teste também a política UTF-8 e a capacidade SMTP do servidor.
O que verificar quando EmailMessage falha ao serializar?
Confirme se a exceção ocorre na conversão da mensagem em bytes ou texto, e não apenas durante o envio. Depois, examine o cabeçalho de destino que a aplicação realmente montou. Compare o mesmo caso com um nome de exibição internacionalizado e endereço ASCII, e com um endereço internacionalizado. Essa comparação isolada ajuda a apontar qual parte do cabeçalho está associada ao erro.
Não conclua pela aparência de uma mensagem impressa no log. A saída pode conter uma representação escapada ou transformada, e não necessariamente os mesmos bytes que o gerador produziu para transmissão. Em um teste controlado, registre o valor do destinatário, a política aplicada e a exceção, sem incluir dados pessoais reais. Para reduzir esse risco nos testes, consulte também as orientações de privacidade do MXTemp.
A política EmailPolicy.utf8 oferece uma opção relacionada ao tratamento de cabeçalhos internacionalizados. A documentação do Python explica o papel dessa opção e os formatos de política disponíveis; a presença do parâmetro, porém, não demonstra que cada dependência, servidor ou destino aceite qualquer endereço. Confira a referência oficial de email.policy e compare a política efetivamente usada na sua aplicação com a documentação da versão em execução.
Endereço EAI e suporte a SMTPUTF8 são verificações distintas
Um endereço EAI tem caracteres não ASCII no próprio endereço, e não apenas no nome de exibição. Para esse caso, há pelo menos duas fronteiras técnicas: a aplicação precisa conseguir representar e serializar a mensagem conforme a política apropriada; o servidor que recebe a solicitação precisa oferecer suporte à extensão SMTPUTF8 quando ela é necessária.
A RFC 6531 especifica a extensão SMTPUTF8 para o transporte SMTP de endereços internacionalizados. Isso não significa que todos os servidores SMTP a implementem, nem que todos os sistemas de recebimento aceitem os mesmos endereços. Na prática, verifique a capacidade anunciada pelo servidor e a resposta obtida na conexão usada pela sua aplicação.
O que acontece se o servidor não oferecer SMTPUTF8?
A biblioteca de envio pode interromper a tentativa e levantar SMTPNotSupportedError quando a mensagem contém endereços não ASCII e o servidor não anuncia o suporte exigido. Esse é um resultado diferente da falha de serialização. A documentação de smtplib e SMTP.send_message descreve essa fronteira e as condições de envio.
O método smtplib.SMTP.send_message não transforma automaticamente um servidor incompatível em um servidor capaz de transportar endereços EAI. Por isso, registre se a exceção acontece antes da operação SMTP, durante a negociação ou em resposta ao comando de envio. Quando a mensagem envolve endereços internacionalizados, confira também a política usada pela chamada e as capacidades anunciadas pelo servidor. A opção de política utf8 e a negociação SMTPUTF8 são partes relacionadas do fluxo, mas não são a mesma etapa.
Comparação para localizar a falha
Use esta comparação para escolher a próxima verificação. Ela descreve evidências a coletar, não garante compatibilidade de uma combinação específica.
| Cenário | Evidência a observar | Próxima verificação |
|---|---|---|
| Nome de exibição não ASCII, endereço ASCII | Cabeçalho produzido e resultado da serialização | Confira a codificação do nome e a política de geração |
| Endereço com caracteres não ASCII | Exceção ao achatar o cabeçalho ou ao preparar o envio | Verifique EmailPolicy.utf8, o endereço montado e a etapa da falha |
| Servidor sem SMTPUTF8 anunciado | Resposta ou SMTPNotSupportedError no envio |
Confirme as capacidades do servidor e a configuração do serviço SMTP |
| Servidor aceita o envio, mas não há mensagem na caixa | Resposta SMTP positiva sem evidência de recebimento | Investigue entrega posterior e confira uma caixa de teste controlada |
A coluna “próxima verificação” evita uma correção prematura. Por exemplo, alterar a política pode ser pertinente quando o erro surge na serialização, mas não fará um servidor anunciar uma extensão ausente. E trocar o servidor não corrige necessariamente um cabeçalho que a aplicação não consegue produzir.
Lembrete: uma resposta SMTP positiva registra que o servidor aceitou a solicitação naquela etapa. Ela não comprova que a mensagem chegou à caixa de entrada, passou por filtros posteriores ou foi exibida ao destinatário.
Roteiro de teste para aplicação própria ou ambiente autorizado
Faça as verificações com endereços de teste sob seu controle ou em um ambiente para o qual você tem autorização. Não use endereços de terceiros nem contas reais de clientes para provocar falhas. Associe cada evidência à mesma execução; misturar um log de serialização com uma resposta SMTP de outra tentativa pode levar a uma conclusão errada.
- Fixe a versão e o caso de teste. Registre a versão do Python usada pelo processo que executa a aplicação. Guarde uma reprodução mínima que contenha o destinatário e a construção do cabeçalho relevantes. Não inclua senhas, tokens ou dados pessoais.
- Separe os tipos de endereço. Monte um caso com nome de exibição internacionalizado e endereço ASCII. Teste separadamente um endereço cuja parte local seja internacionalizada, se esse formato fizer parte do requisito do produto. Não trate os dois casos como equivalentes.
- Inspecione a mensagem antes do envio. Verifique os campos de remetente e destinatário, a política do objeto e a operação que serializa a mensagem. Registre o tipo da exceção e a saída serializada quando houver. Se falhar aqui, ainda não há evidência de que o servidor SMTP tenha sido consultado.
- Verifique a capacidade do servidor. Confira a resposta de capacidades após a conexão e identifique se SMTPUTF8 é anunciado. Registre a resposta SMTP ou a exceção completa. Para um endereço EAI, a ausência da extensão necessária é uma pista relevante; não substitua essa verificação por uma tentativa com um endereço ASCII.
- Execute o envio e registre a resposta. Faça o teste pelo mesmo caminho usado pela aplicação, incluindo
smtplib.SMTP.send_messagequando esse for o método em produção. Anote se a mensagem foi serializada, se o servidor aceitou a solicitação ou se a biblioteca encerrou o processo com uma exceção. - Confirme o recebimento em uma caixa controlada. Verifique se a mensagem apareceu e confira os cabeçalhos que chegaram. Registre a caixa de destino usada, o tipo de endereço, o resultado do envio e a evidência de recebimento. Se a mensagem não aparecer, não classifique o teste como aprovado só porque o servidor aceitou o envio.
- Repita apenas a variável necessária. Se você mudar a política, o servidor, o endereço ou uma dependência, registre a alteração e repita o caso afetado. Isso mantém claro se a correção resolveu a geração, a negociação SMTP ou o recebimento real.
Como confirmar que o e-mail de teste chegou de verdade depois da geração?
Use uma caixa de destino controlada e verifique a mensagem nela, em vez de inferir a entrega a partir do resultado da serialização ou do retorno do envio. Correlacione o cabeçalho recebido com a mesma tentativa registrada na aplicação. Caso não exista uma evidência na caixa de destino, a conclusão segura é “solicitação aceita pelo servidor”, não “mensagem recebida”.
Para executar esse tipo de verificação com dados de teste, uma caixa temporária pode ser uma opção para mensagens de um produto próprio. O MXTemp oferece acesso a uma caixa temporária sem cadastro, mas isso não comprova compatibilidade com endereços EAI, não substitui a verificação da negociação SMTP e não garante entrega. Confirme primeiro se o endereço de destino escolhido serve para o cenário que está sendo validado.
Correção conforme a parte que falhou
Se apenas o nome de exibição contém caracteres internacionais e o endereço permanece ASCII, concentre a revisão no cabeçalho gerado e na política usada para serializá-lo. Observe o resultado concreto e a exceção; não altere o endereço real apenas para ocultar uma falha de codificação.
Se o endereço em si é internacionalizado, examine a interpretação do endereço, a política de geração e o resultado da serialização. Depois, confirme que o servidor SMTP anuncia e aceita SMTPUTF8. A documentação indica as opções relevantes, mas a correção precisa corresponder às dependências e ao serviço de envio efetivamente usados pelo projeto.
Se o servidor não suporta a extensão necessária, trate isso como uma limitação da rota de envio, não como prova de que o Python rejeita todos os endereços internacionais. Avalie com o responsável pelo serviço SMTP se existe uma rota compatível ou se o produto deve comunicar uma limitação de suporte. Não faça conversões improvisadas do endereço: elas podem mudar o destinatário e invalidar o teste.
Por fim, defina o alcance da conclusão com precisão. Um teste pode confirmar que determinada versão do Python gerou certo cabeçalho para um tipo específico de endereço, que uma rota SMTP aceitou a mensagem e que uma caixa controlada a recebeu. Isso não autoriza afirmar compatibilidade com todos os domínios, servidores ou sistemas de e-mail.
Para mensagens de QA, demonstrações e testes de cadastro do próprio produto, uma caixa controlada ajuda a manter os dados de teste separados do e-mail pessoal e a observar o recebimento real. O MXTemp pode ser uma alternativa prática para uma verificação temporária, sem expor o endereço principal; a adequação depende do endereço usado e do suporte exigido pelo seu cenário. Para mensagens que precisam de respostas, histórico duradouro ou recuperação de contas importantes, prefira um endereço sob controle permanente. O teste só está concluído quando a evidência corresponde à etapa que você queria validar.