# `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`. 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
  - `EmailMessage`
    - `as_string()`
    - `__str__()`
    - `as_bytes()`
    - `__bytes__()`
    - `is_multipart()`
    - `set_unixfrom()`
    - `get_unixfrom()`
    - `__len__()`
    - `__contains__()`
    - `__getitem__()`
    - `__setitem__()`
    - `__delitem__()`
    - `keys()`
    - `values()`
    - `items()`
    - `get()`
    - `get_all()`
    - `add_header()`
    - `replace_header()`
    - `get_content_type()`
    - `get_content_maintype()`
    - `get_content_subtype()`
    - `get_default_type()`
    - `set_default_type()`
    - `set_param()`
    - `del_param()`
    - `get_filename()`
    - `get_boundary()`
    - `set_boundary()`
    - `get_content_charset()`
    - `get_charsets()`
    - `is_attachment()`
    - `get_content_disposition()`
    - `walk()`
    - `get_body()`
    - `iter_attachments()`
    - `iter_parts()`
    - `get_content()`
    - `set_content()`
    - `make_related()`
    - `make_alternative()`
    - `make_mixed()`
    - `add_related()`
    - `add_alternative()`
    - `add_attachment()`
    - `clear()`
    - `clear_content()`
    - `preamble`
    - `epilogue`
    - `defects`
  - `MIMEPart`
- `email.parser`: Parsing email messages
  - API do FeedParser
    - `BytesFeedParser`
      - `feed()`
      - `close()`
    - `FeedParser`
  - Parser API
    - `BytesParser`
      - `parse()`
      - `parsebytes()`
    - `BytesHeaderParser`
    - `Parser`
      - `parse()`
      - `parsestr()`
    - `HeaderParser`
    - `message_from_bytes()`
    - `message_from_binary_file()`
    - `message_from_string()`
    - `message_from_file()`
  - Additional notes
- `email.generator`: Generating MIME documents
  - `BytesGenerator`
    - `flatten()`
    - `clone()`
    - `write()`
  - `Generator`
    - `flatten()`
    - `clone()`
    - `write()`
  - `DecodedGenerator`
- `email.policy`: Policy Objects
  - `Policy`
    - `max_line_length`
    - `linesep`
    - `cte_type`
    - `raise_on_defect`
    - `mangle_from_`
    - `message_factory`
    - `verify_generated_headers`
    - `clone()`
    - `handle_defect()`
    - `register_defect()`
    - `header_max_count()`
    - `header_source_parse()`
    - `header_store_parse()`
    - `header_fetch_parse()`
    - `fold()`
    - `fold_binary()`
  - `EmailPolicy`
    - `utf8`
    - `refold_source`
    - `header_factory`
    - `content_manager`
    - `header_max_count()`
    - `header_source_parse()`
    - `header_store_parse()`
    - `header_fetch_parse()`
    - `fold()`
    - `fold_binary()`
  - `default`
  - `SMTP`
  - `SMTPUTF8`
  - `HTTP`
  - `strict`
  - `Compat32`
    - `mangle_from_`
    - `header_source_parse()`
    - `header_store_parse()`
    - `header_fetch_parse()`
    - `fold()`
    - `fold_binary()`
  - `compat32`
- `email.errors`: Exception and Defect classes
  - `MessageError`
  - `MessageParseError`
  - `HeaderParseError`
  - `BoundaryError`
  - `MultipartConversionError`
  - `HeaderWriteError`
  - `MessageDefect`
  - `HeaderDefect`
- `email.headerregistry`: Custom Header Objects
  - `BaseHeader`
    - `name`
    - `defects`
    - `max_count`
    - `fold()`
  - `UnstructuredHeader`
  - `DateHeader`
    - `datetime`
  - `AddressHeader`
    - `groups`
    - `addresses`
  - `SingleAddressHeader`
    - `address`
  - `MIMEVersionHeader`
    - `version`
    - `major`
    - `minor`
  - `ParameterizedMIMEHeader`
    - `params`
  - `ContentTypeHeader`
    - `content_type`
    - `maintype`
    - `subtype`
  - `ContentDispositionHeader`
    - `content_disposition`
  - `ContentTransferEncoding`
    - `cte`
  - `HeaderRegistry`
    - `map_to_type()`
    - `__getitem__()`
    - `__call__()`
  - `Address`
    - `display_name`
    - `username`
    - `domain`
    - `addr_spec`
    - `__str__()`
  - `Group`
    - `display_name`
    - `addresses`
    - `__str__()`
- `email.contentmanager`: Managing MIME Content
  - `ContentManager`
    - `get_content()`
    - `set_content()`
    - `add_get_handler()`
    - `add_set_handler()`
  - Content Manager Instances
    - `raw_data_manager`
      - `get_content()`
      - `set_content()`
- `email`: Exemplos

API legada

- `email.message.Message`: Representing an email message using the `compat32` API
  - `Message`
    - `as_string()`
    - `__str__()`
    - `as_bytes()`
    - `__bytes__()`
    - `is_multipart()`
    - `set_unixfrom()`
    - `get_unixfrom()`
    - `attach()`
    - `get_payload()`
    - `set_payload()`
    - `set_charset()`
    - `get_charset()`
    - `__len__()`
    - `__contains__()`
    - `__getitem__()`
    - `__setitem__()`
    - `__delitem__()`
    - `keys()`
    - `values()`
    - `items()`
    - `get()`
    - `get_all()`
    - `add_header()`
    - `replace_header()`
    - `get_content_type()`
    - `get_content_maintype()`
    - `get_content_subtype()`
    - `get_default_type()`
    - `set_default_type()`
    - `get_params()`
    - `get_param()`
    - `set_param()`
    - `del_param()`
    - `set_type()`
    - `get_filename()`
    - `get_boundary()`
    - `set_boundary()`
    - `get_content_charset()`
    - `get_charsets()`
    - `get_content_disposition()`
    - `walk()`
    - `preamble`
    - `epilogue`
    - `defects`
- `email.mime`: Creating email and MIME objects from scratch
  - `MIMEBase`
  - `MIMENonMultipart`
  - `MIMEMultipart`
  - `MIMEApplication`
  - `MIMEAudio`
  - `MIMEImage`
  - `MIMEMessage`
  - `MIMEText`
- `email.header`: Internationalized headers
  - `Header`
    - `append()`
    - `encode()`
    - `__str__()`
    - `__eq__()`
    - `__ne__()`
  - `decode_header()`
  - `make_header()`
- `email.charset`: Representing character sets
  - `Charset`
    - `input_charset`
    - `header_encoding`
    - `body_encoding`
    - `output_charset`
    - `input_codec`
    - `output_codec`
    - `get_body_encoding()`
    - `get_output_charset()`
    - `header_encode()`
    - `header_encode_lines()`
    - `body_encode()`
    - `__str__()`
    - `__eq__()`
    - `__ne__()`
  - `add_charset()`
  - `add_alias()`
  - `add_codec()`
- `email.encoders`: Encoders
  - `encode_quopri()`
  - `encode_base64()`
  - `encode_7or8bit()`
  - `encode_noop()`
- `email.utils`: Utilitários diversos
  - `localtime()`
  - `make_msgid()`
  - `quote()`
  - `unquote()`
  - `parseaddr()`
  - `formataddr()`
  - `getaddresses()`
  - `parsedate()`
  - `parsedate_tz()`
  - `parsedate_to_datetime()`
  - `mktime_tz()`
  - `formatdate()`
  - `format_datetime()`
  - `decode_rfc2231()`
  - `encode_rfc2231()`
  - `collapse_rfc2231_value()`
  - `decode_params()`
- `email.iterators`: Iteradores
  - `body_line_iterator()`
  - `typed_subpart_iterator()`
  - `_structure()`

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 `mailbox`

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