email — An email and MIME handling package¶

Source code:Lib/email/__init__.py

Theemail package is a library for managing email messages. It isspecificallynot designed to do any sending of email messages to SMTP(RFC 2821), NNTP, or other servers; those are functions of modules such assmtplib. Theemail package attempts to be asRFC-compliant as possible, supportingRFC 5322 andRFC 6532, as well assuch MIME-related RFCs asRFC 2045,RFC 2046,RFC 2047,RFC 2183,andRFC 2231.

The overall structure of the email package can be divided into three majorcomponents, plus a fourth component that controls the behavior of the othercomponents.

The central component of the package is an “object model” that represents emailmessages. An application interacts with the package primarily through theobject model interface defined in themessage sub-module. Theapplication can use this API to ask questions about an existing email, toconstruct a new email, or to add or remove email subcomponents that themselvesuse the same object model interface. That is, following the nature of emailmessages and their MIME subcomponents, the email object model is a treestructure of objects that all provide theEmailMessageAPI.

The other two major components of the package are theparser andthegenerator. The parser takes the serialized version of anemail message (a stream of bytes) and converts it into a tree ofEmailMessage objects. The generator takes anEmailMessage and turns it back into a serialized bytestream. (The parser and generator also handle streams of text characters, butthis usage is discouraged as it is too easy to end up with messages that arenot valid in one way or another.)

The control component is thepolicy module. EveryEmailMessage, everygenerator, and everyparser has an associatedpolicy object thatcontrols its behavior. Usually an application only needs to specify the policywhen anEmailMessage is created, either by directlyinstantiating anEmailMessage to create a new email,or by parsing an input stream using aparser. But the policy canbe changed when the message is serialized using agenerator.This allows, for example, a generic email message to be parsed from disk, butto serialize it using standard SMTP settings when sending it to an emailserver.

The email package does its best to hide the details of the various governingRFCs from the application. Conceptually the application should be able totreat the email message as a structured tree of unicode text and binaryattachments, without having to worry about how these are represented whenserialized. In practice, however, it is often necessary to be aware of atleast some of the rules governing MIME messages and their structure,specifically the names and nature of the MIME “content types” and how theyidentify multipart documents. For the most part this knowledge should only berequired for more complex applications, and even then it should only be thehigh level structure in question, and not the details of how those structuresare represented. Since MIME content types are used widely in modern internetsoftware (not just email), this will be a familiar concept to many programmers.

The following sections describe the functionality of theemail package.We start with themessage object model, which is the primaryinterface an application will use, and follow that with theparser andgenerator components. Then we cover thepolicy controls, which completes the treatment of the maincomponents of the library.

The next three sections cover the exceptions the package may raise and thedefects (non-compliance with the RFCs) that theparser maydetect. Then we cover theheaderregistry and thecontentmanager sub-components, which provide tools for doing moredetailed manipulation of headers and payloads, respectively. Both of thesecomponents contain features relevant to consuming and producing non-trivialmessages, but also document their extensibility APIs, which will be of interestto advanced applications.

Following those is a set of examples of using the fundamental parts of the APIscovered in the preceding sections.

The foregoing represent the modern (unicode friendly) API of the email package.The remaining sections, starting with theMessageclass, cover the legacycompat32 API that deals much moredirectly with the details of how email messages are represented. Thecompat32 API doesnot hide the details of the RFCs fromthe application, but for applications that need to operate at that level, theycan be useful tools. This documentation is also relevant for applications thatare still using thecompat32 API for backwardcompatibility reasons.

Contents of theemail package documentation:

Legacy API: