# `email` — Um e-mail e um pacote MIME manipulável

Código-fonte: Lib/email/__init__.py

O pacote `email` é uma biblioteca para gerenciar mensagens de e-mail. Ela foi especificamente não projetada para enviar mensagens de e-mail para SMTP (RFC 2821), NNTP ou outros servidores; essas são funções de módulos como `smtplib` e `nntplib`. O pacote `email` tenta ser o mais compatível possível com RFC, suportando RFC 5322 e RFC 6532, bem como os RFCs relacionados ao MIME como RFC 2045, RFC 2046, RFC 2047, RFC 2183 e RFC 2231.

No geral a estrutura do pacote de e-mail pode ser dividida em três componentes principais, mais um quarto componente que controla o comportamento dos outros componentes.

O componente central do pacote é um “modelo de objeto” que representa mensagens de e-mail. Uma aplicação interage com o pacote principalmente através da interface do modelo de objeto definida no submódulo `message`. A aplicação pode usar essa API para fazer perguntas sobre um e-mail existente, construir um novo e-mail ou adicionar ou remover subcomponentes de e-mail que usam a mesma interface de modelo de objeto. Ou seja, seguindo a natureza das mensagens de e-mail e seus subcomponentes MIME, o modelo de objeto de e-mail é uma estrutura em árvore de objetos que fornecem a API `EmailMessage`.

Os outros dois componentes principais do pacote são `parser` e `generator`. O analisador sintático pega a versão serializada de uma mensagem de e-mail (um fluxo de bytes) e a converte em uma árvore de objetos `EmailMessage`. O gerador pega um `EmailMessage` e o transforma novamente em um fluxo de bytes serializado. (O analisador sintático e o gerador também lidam com fluxos de caracteres de texto, mas esse uso é desencorajado, pois é muito fácil terminar com mensagens que não são válidas de uma maneira ou de outra.)

O componente de controle é o módulo `policy`. Cada `EmailMessage`, cada `generator` e cada `parser` tem um objeto associado `policy` que controla seu comportamento. Normalmente, uma aplicação precisa especificar a política apenas quando uma `EmailMessage` é criada, instanciando diretamente uma `EmailMessage` para criar um novo e-mail ou analisando um fluxo de entrada usando um `parser`. Mas a política pode ser alterada quando a mensagem é serializada usando um `generator`. Isso permite, por exemplo, analisar uma mensagem de e-mail genérica do disco, mas serializá-la usando as configurações SMTP padrão ao enviá-la para um servidor de e-mail.

O pacote de e-mail faz o possível para ocultar os detalhes das várias RFCs em vigor da aplicação. Conceitualmente, a aplicação deve tratar a mensagem de e-mail como uma árvore estruturada de texto unicode e anexos binários, sem ter que se preocupar com a forma como eles são representados quando serializados. Na prática, no entanto, muitas vezes é necessário estar ciente de pelo menos algumas das regras que regem as mensagens MIME e sua estrutura, especificamente os nomes e a natureza dos “tipos de conteúdo” MIME e como eles identificam documentos com várias partes. Na maioria das vezes, esse conhecimento só deve ser necessário para aplicações mais complexos e, mesmo assim, deve ser apenas a estrutura de alto nível em questão, e não os detalhes de como essas estruturas são representadas. Como os tipos de conteúdo MIME são amplamente utilizados no software moderno da Internet (não apenas no e-mail), este será um conceito familiar para muitos programadores.

As seções a seguir descrevem a funcionalidade do pacote `email`. Começamos com o modelo de objeto `message`, que é a interface principal que uma aplicação usará, e seguimos com os componentes de `parser` e `generator`. Em seguida, abordamos os controles `policy`, que concluem o tratamento dos principais componentes da biblioteca.

As próximas três seções cobrem as exceções que o pacote pode apresentar e os defeitos (não conformidade com as RFCs) que o `parser` pode detectar. A seguir, abordamos os subcomponentes `headerregistry` e os subcomponentes `contentmanager`, que fornecem ferramentas para manipulação mais detalhada de cabeçalhos e cargas úteis, respectivamente. Ambos os componentes contêm recursos relevantes para consumir e produzir mensagens não triviais, mas também documentam suas APIs de extensibilidade, que serão de interesse para aplicações avançadas.

A seguir, é apresentado um conjunto de exemplos de uso das partes fundamentais das APIs abordadas nas seções anteriores.

O exposto acima representa a API moderna (compatível com unicode) do pacote de e-mail. As seções restantes, começando com a classe `Message`, cobrem a API legada `compat32` que lida muito mais diretamente com os detalhes de como as mensagens de e-mail são representadas. A API `compat32` não oculta os detalhes dos RFCs da aplicação, mas para aplicações que precisam operar nesse nível, eles podem ser ferramentas úteis. Esta documentação também é relevante para aplicações que ainda estão usando a API `compat32` por motivos de compatibilidade com versões anteriores.

Alterado na versão 3.6: Documentos reorganizados e reescritos para promover a nova API `EmailMessage`/`EmailPolicy`.

Conteúdos da documentação do pacote `email`:

- `email.message`: Representing an email message
- `email.parser`: Parsing email messages
  - API do FeedParser
  - Parser API
  - Additional notes
- `email.generator`: Geração de documentos MIME
- `email.policy`: Policy Objects
- `email.errors`: Classes de Exceção e Defeito.
- `email.headerregistry`: Custom Header Objects
- `email.contentmanager`: Gerenciando conteúdo MIME
  - Content Manager Instances
- `email`: Exemplos

API legada

- `email.message.Message`: Representing an email message using the `compat32` API
- `email.mime` `email.mime`: Criando e-mail e objetos MIME do zero
- `email.header`: Internationalized headers
- `email.charset`: Representando conjuntos de caracteres
- `email.encoders`: Codificadores
- `email.utils`: Utilitários diversos
- `email.iterators`: Iteradores

Ver também

Módulo `smtplib`

  Cliente SMTP (Protocolo Simples de Envio de E-mail)

Módulo `poplib`

  Cliente POP (Post Office Protocol)

Módulo `imaplib`

  Cliente IMAP (Internet Message Access Protocol)

Módulo `nntplib`

  Cliente NNTP (Network News Transport Protocol)

Módulo `mailbox`

  Ferramentas para criar, ler, e gerenciar coleções de mensagem em disco usando vários formatos padrão.