1:mod:`email` --- An email and MIME handling package
2===================================================
3
4.. module:: email
5   :synopsis: Package supporting the parsing, manipulating, and generating
6              email messages.
7.. moduleauthor:: Barry A. Warsaw <barry@python.org>,
8                  R. David Murray <rdmurray@bitdance.com>
9.. sectionauthor:: R. David Murray <rdmurray@bitdance.com>
10
11**Source code:** :source:`Lib/email/__init__.py`
12
13--------------
14
15The :mod:`email` package is a library for managing email messages.  It is
16specifically *not* designed to do any sending of email messages to SMTP
17(:rfc:`2821`), NNTP, or other servers; those are functions of modules such as
18:mod:`smtplib` and :mod:`nntplib`.  The :mod:`email` package attempts to be as
19RFC-compliant as possible, supporting :rfc:`5322` and :rfc:`6532`, as well as
20such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`,
21and :rfc:`2231`.
22
23The overall structure of the email package can be divided into three major
24components, plus a fourth component that controls the behavior of the other
25components.
26
27The central component of the package is an "object model" that represents email
28messages.  An application interacts with the package primarily through the
29object model interface defined in the :mod:`~email.message` sub-module.  The
30application can use this API to ask questions about an existing email, to
31construct a new email, or to add or remove email subcomponents that themselves
32use the same object model interface.  That is, following the nature of email
33messages and their MIME subcomponents, the email object model is a tree
34structure of objects that all provide the :class:`~email.message.EmailMessage`
35API.
36
37The other two major components of the package are the :mod:`~email.parser` and
38the :mod:`~email.generator`.  The parser takes the serialized version of an
39email message (a stream of bytes) and converts it into a tree of
40:class:`~email.message.EmailMessage` objects.  The generator takes an
41:class:`~email.message.EmailMessage` and turns it back into a serialized byte
42stream.  (The parser and generator also handle streams of text characters, but
43this usage is discouraged as it is too easy to end up with messages that are
44not valid in one way or another.)
45
46The control component is the :mod:`~email.policy` module.  Every
47:class:`~email.message.EmailMessage`, every :mod:`~email.generator`, and every
48:mod:`~email.parser` has an associated :mod:`~email.policy` object that
49controls its behavior.  Usually an application only needs to specify the policy
50when an :class:`~email.message.EmailMessage` is created, either by directly
51instantiating an :class:`~email.message.EmailMessage`  to create a new email,
52or by parsing an input stream using a :mod:`~email.parser`.  But the policy can
53be changed when the message is serialized using a :mod:`~email.generator`.
54This allows, for example, a generic email message to be parsed from disk, but
55to serialize it using standard SMTP settings when sending it to an email
56server.
57
58The email package does its best to hide the details of the various governing
59RFCs from the application.  Conceptually the application should be able to
60treat the email message as a structured tree of unicode text and binary
61attachments, without having to worry about how these are represented when
62serialized.  In practice, however, it is often necessary to be aware of at
63least some of the rules governing MIME messages and their structure,
64specifically the names and nature of the MIME "content types" and how they
65identify multipart documents.  For the most part this knowledge should only be
66required for more complex applications, and even then it should only be the
67high level structure in question, and not the details of how those structures
68are represented.  Since MIME content types are used widely in modern internet
69software (not just email), this will be a familiar concept to many programmers.
70
71The following sections describe the functionality of the :mod:`email` package.
72We start with the :mod:`~email.message` object model, which is the primary
73interface an application will use, and follow that with the
74:mod:`~email.parser` and :mod:`~email.generator` components.  Then we cover the
75:mod:`~email.policy` controls, which completes the treatment of the main
76components of the library.
77
78The next three sections cover the exceptions the package may raise and the
79defects (non-compliance with the RFCs) that the :mod:`~email.parser` may
80detect.  Then we cover the :mod:`~email.headerregistry` and the
81:mod:`~email.contentmanager` sub-components, which provide tools for doing more
82detailed manipulation of headers and payloads, respectively.  Both of these
83components contain features relevant to consuming and producing non-trivial
84messages, but also document their extensibility APIs, which will be of interest
85to advanced applications.
86
87Following those is a set of examples of using the fundamental parts of the APIs
88covered in the preceding sections.
89
90The foregoing represent the modern (unicode friendly) API of the email package.
91The remaining sections, starting with the :class:`~email.message.Message`
92class, cover the legacy :data:`~email.policy.compat32` API that deals much more
93directly with the details of how email messages are represented.  The
94:data:`~email.policy.compat32` API does *not* hide the details of the RFCs from
95the application, but for applications that need to operate at that level, they
96can be useful tools.  This documentation is also relevant for applications that
97are still using the :mod:`~email.policy.compat32` API for backward
98compatibility reasons.
99
100.. versionchanged:: 3.6
101   Docs reorganized and rewritten to promote the new
102   :class:`~email.message.EmailMessage`/:class:`~email.policy.EmailPolicy`
103   API.
104
105Contents of the :mod:`email` package documentation:
106
107.. toctree::
108
109   email.message.rst
110   email.parser.rst
111   email.generator.rst
112   email.policy.rst
113
114   email.errors.rst
115   email.headerregistry.rst
116   email.contentmanager.rst
117
118   email.examples.rst
119
120Legacy API:
121
122.. toctree::
123
124   email.compat32-message.rst
125   email.mime.rst
126   email.header.rst
127   email.charset.rst
128   email.encoders.rst
129   email.utils.rst
130   email.iterators.rst
131
132
133.. seealso::
134
135   Module :mod:`smtplib`
136      SMTP (Simple Mail Transport Protocol) client
137
138   Module :mod:`poplib`
139      POP (Post Office Protocol) client
140
141   Module :mod:`imaplib`
142      IMAP (Internet Message Access Protocol) client
143
144   Module :mod:`nntplib`
145      NNTP (Net News Transport Protocol) client
146
147   Module :mod:`mailbox`
148      Tools for creating, reading, and managing collections of messages on disk
149      using a variety standard formats.
150
151   Module :mod:`smtpd`
152      SMTP server framework (primarily useful for testing)
153