O módulo email.headerregistry oferece uma forma moderna e estruturada de trabalhar com cabeçalhos de e-mail no Python. Em vez de tratar campos como From, To, Subject e Date apenas como strings, ele cria objetos especializados que entendem endereços, grupos, parâmetros, datas e regras de formatação. Isso reduz erros comuns ao montar mensagens, facilita validações e torna o código mais legível.
Neste guia, você vai aprender como o registro de cabeçalhos funciona, quando ele é usado automaticamente pelo pacote email, como acessar endereços de forma segura e como criar mensagens compatíveis com os padrões atuais.
O que é email.headerregistry
O pacote email do Python possui políticas que controlam como uma mensagem é analisada e serializada. Ao usar uma política moderna, como email.policy.default, os cabeçalhos deixam de ser strings simples e passam a ser instâncias de classes apropriadas. Um cabeçalho de endereço pode expor caixas de correio e grupos; um cabeçalho de data pode fornecer um objeto datetime; um cabeçalho com parâmetros pode separar o valor principal de atributos como charset e boundary.
O HeaderRegistry é o componente que decide qual classe deve representar cada nome de cabeçalho. Ele conhece campos padronizados e também oferece um tipo genérico para campos personalizados.
Criando uma mensagem com política moderna
from email.message import EmailMessage
from email.policy import default
msg = EmailMessage(policy=default)
msg["From"] = "Equipe Academify <contato@example.com>"
msg["To"] = "Aluno <aluno@example.com>"
msg["Subject"] = "Confirmação de matrícula"
msg.set_content("Sua matrícula foi confirmada.")
Ao consultar msg["From"], o resultado se comporta como texto quando impresso, mas também possui propriedades estruturadas. Isso permite trabalhar com os dados sem dividir strings manualmente.
cabecalho = msg["From"]
print(cabecalho.addresses[0].display_name)
print(cabecalho.addresses[0].username)
print(cabecalho.addresses[0].domain)
Essa abordagem é muito mais robusta do que usar split("@"), pois nomes de exibição, aspas, comentários e endereços internacionais tornam a sintaxe real de e-mail mais complexa.
Trabalhando com Address
A classe Address representa uma caixa postal individual. Você pode criá-la diretamente e atribuí-la a um cabeçalho.
from email.headerregistry import Address
remetente = Address(
display_name="Suporte Academify",
username="suporte",
domain="example.com",
)
msg["From"] = remetente
Separar nome, usuário e domínio evita problemas de escape e codificação. O pacote se encarrega de colocar aspas quando necessário e de gerar uma representação adequada.
Também é possível adicionar vários destinatários:
msg["To"] = (
Address("Ana", "ana", "example.com"),
Address("Carlos", "carlos", "example.com"),
)
Para projetos maiores, vale combinar essa técnica com boas práticas de funções, tipos e validação. Veja também os conteúdos sobre Type Hints no Python e funções em Python.
Grupos de destinatários
O padrão de e-mail permite grupos nomeados, como uma lista chamada “Equipe”. O headerregistry representa isso com a classe Group.
from email.headerregistry import Address, Group
grupo = Group(
display_name="Equipe",
addresses=(
Address("Ana", "ana", "example.com"),
Address("Carlos", "carlos", "example.com"),
),
)
msg["To"] = grupo
Ao analisar mensagens recebidas, a propriedade groups permite recuperar esses agrupamentos sem escrever um parser próprio.
Cabeçalhos de data
Campos como Date ganham uma propriedade datetime. Isso facilita comparações, conversões de fuso horário e ordenação.
from datetime import datetime, timezone
msg["Date"] = datetime.now(timezone.utc)
data = msg["Date"].datetime
print(data.isoformat())
Para dominar conversões de horário, consulte o guia de datas e horas com datetime e o artigo sobre zoneinfo no Python.
Cabeçalhos com parâmetros
Alguns campos possuem parâmetros, como Content-Type: text/plain; charset="utf-8". Objetos de cabeçalho estruturados expõem o valor principal e os parâmetros de maneira previsível. Em geral, você deve preferir os métodos de alto nível de EmailMessage, como set_content, add_attachment e add_alternative, porque eles configuram esses campos corretamente.
msg.set_content("Olá, mundo!", charset="utf-8")
print(msg.get_content_type())
print(msg.get_content_charset())
Evite montar manualmente limites MIME ou codificações. Pequenos erros podem produzir mensagens que funcionam em um cliente e falham em outro.
Analisando mensagens recebidas
from email import policy
from email.parser import BytesParser
with open("mensagem.eml", "rb") as arquivo:
recebida = BytesParser(policy=policy.default).parse(arquivo)
for endereco in recebida["To"].addresses:
print(endereco.display_name, endereco.addr_spec)
O uso de policy.default é importante. Políticas antigas podem retornar strings tradicionais, limitando as propriedades estruturadas. Ao processar arquivos, aplique também cuidados apresentados no guia sobre como usar with para abrir arquivos.
Defeitos e validação
Mensagens reais nem sempre seguem perfeitamente os padrões. Objetos de cabeçalho podem registrar anomalias na propriedade defects. Isso é útil para decidir se uma mensagem deve ser aceita, corrigida, isolada ou rejeitada.
assunto = recebida["Subject"]
if assunto.defects:
for defeito in assunto.defects:
print(type(defeito).__name__, defeito)
Não trate a ausência de defeitos como validação de segurança completa. Endereços podem estar sintaticamente corretos e ainda ser falsos, maliciosos ou não autorizados. Em sistemas web, valide permissões, limites de tamanho e origem dos dados.
HeaderRegistry personalizado
Em aplicações especializadas, você pode instanciar HeaderRegistry e mapear nomes personalizados para classes próprias. Esse recurso é avançado e normalmente só é necessário quando sua organização usa cabeçalhos internos com sintaxe específica. Para a maioria dos projetos, o registro padrão já cobre os campos relevantes.
Ao personalizar, mantenha compatibilidade com a interface esperada pelo pacote e crie testes para serialização e análise. O artigo sobre testes unitários no Python ajuda a estruturar esses cenários.
Boas práticas
Use EmailMessage com policy.default, construa destinatários com Address, prefira métodos de alto nível para conteúdo MIME e nunca concatene dados não confiáveis diretamente em cabeçalhos. Remova quebras de linha de entradas externas para evitar injeção de cabeçalho. Defina limites para quantidade de destinatários, tamanho de assunto e anexos. Ao registrar logs, evite expor endereços completos ou conteúdo sensível.
Também é importante testar o resultado final com msg.as_bytes() e com os provedores usados em produção. Diferentes servidores podem aplicar regras extras de codificação, autenticação e tamanho.
Quando usar
O email.headerregistry é indicado para sistemas que criam notificações, analisam arquivos EML, processam caixas postais, geram relatórios de entrega ou precisam extrair destinatários de forma confiável. Para um envio simples, talvez você não use o módulo diretamente, mas ele continuará trabalhando nos bastidores quando a política moderna estiver ativa.
Conclusão
Tratar cabeçalhos como objetos estruturados torna o processamento de e-mails mais seguro e fácil de manter. Com Address, Group, políticas modernas e propriedades específicas, você evita parsers frágeis e produz mensagens mais compatíveis. Consulte a documentação oficial de email.headerregistry e a RFC 5322 para detalhes completos do formato.
