# 12.2 `email` -- An email and MIME handling package

New in version 2.2.

The `email` package is a library for managing email messages, including MIME and other RFC 2822-based message documents. It subsumes most of the functionality in several older standard modules such as `rfc822`, `mimetools`, `multifile`, and other non-standard packages such as `mimecntl`. It is specifically not designed to do any sending of email messages to SMTP (RFC 2821) servers; that is the function of the `smtplib` module12.1.

The primary distinguishing feature of the `email` package is that it splits the parsing and generating of email messages from the internal object model representation of email. Applications using the `email` package deal primarily with objects; you can add sub-objects to messages, remove sub-objects from messages, completely re-arrange the contents, etc. There is a separate parser and a separate generator which handles the transformation from flat text to the object model, and then back to flat text again. There are also handy subclasses for some common MIME object types, and a few miscellaneous utilities that help with such common tasks as extracting and parsing message field values, creating RFC-compliant dates, etc.

The following sections describe the functionality of the `email` package. The ordering follows a progression that should be common in applications: an email message is read as flat text from a file or other source, the text is parsed to produce an object model representation of the email message, this model is manipulated, and finally the model is rendered back into flat text.

It is perfectly feasible to create the object model out of whole cloth -- i.e. completely from scratch. From there, a similar progression can be taken as above.

Also included are detailed specifications of all the classes and modules that the `email` package provides, the exception classes you might encounter while using the `email` package, some auxiliary utilities, and a few examples. For users of the older `mimelib` package, from which the `email` package is descended, a section on differences and porting is provided.

See Also:

Module `smtplib`:
  SMTP protocol client.

#### Footnotes

... module 12.1
  For this reason, line endings in the `email` package are always native line endings. The `smtplib` module is responsible for converting from native line endings to RFC 2821 line endings, just as your mail server would be responsible for converting from RFC 2821 line endings to native line endings when it stores messages in a local mailbox.

Subsections

- 12.2.1 Representing an email message
- 12.2.2 Parsing email messages
  - 12.2.2.1 Parser class API
  - 12.2.2.2 Additional notes
- 12.2.3 Generating MIME documents
- 12.2.4 Creating email and MIME objects from scratch
- 12.2.5 Encoders
- 12.2.6 Exception classes
- 12.2.7 Miscellaneous utilities
- 12.2.8 Iterators
- 12.2.9 Differences from `mimelib`
- 12.2.10 Examples