| 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 <[email protected]>, |
| 8 |
R. David Murray <[email protected]> |
| 9 |
.. sectionauthor:: R. David Murray <[email protected]> |
| 10 |
|
| 11 |
**Source code:** :source:`Lib/email/__init__.py` |
| 12 |
|
| 13 |
-------------- |
| 14 |
|
| 15 |
The :mod:`!email` package is a library for managing email messages. It is |
| 16 |
specifically *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`. The :mod:`!email` package attempts to be as |
| 19 |
RFC-compliant as possible, supporting :rfc:`5322` and :rfc:`6532`, as well as |
| 20 |
such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`, |
| 21 |
and :rfc:`2231`. |
| 22 |
|
| 23 |
The overall structure of the email package can be divided into three major |
| 24 |
components, plus a fourth component that controls the behavior of the other |
| 25 |
components. |
| 26 |
|
| 27 |
The central component of the package is an "object model" that represents email |
| 28 |
messages. An application interacts with the package primarily through the |
| 29 |
object model interface defined in the :mod:`~email.message` sub-module. The |
| 30 |
application can use this API to ask questions about an existing email, to |
| 31 |
construct a new email, or to add or remove email subcomponents that themselves |
| 32 |
use the same object model interface. That is, following the nature of email |
| 33 |
messages and their MIME subcomponents, the email object model is a tree |
| 34 |
structure of objects that all provide the :class:`~email.message.EmailMessage` |
| 35 |
API. |
| 36 |
|
| 37 |
The other two major components of the package are the :mod:`~email.parser` and |
| 38 |
the :mod:`~email.generator`. The parser takes the serialized version of an |
| 39 |
email 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 |
| 42 |
stream. (The parser and generator also handle streams of text characters, but |
| 43 |
this usage is discouraged as it is too easy to end up with messages that are |
| 44 |
not valid in one way or another.) |
| 45 |
|
| 46 |
The 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 |
| 49 |
controls its behavior. Usually an application only needs to specify the policy |
| 50 |
when an :class:`~email.message.EmailMessage` is created, either by directly |
| 51 |
instantiating an :class:`~email.message.EmailMessage` to create a new email, |
| 52 |
or by parsing an input stream using a :mod:`~email.parser`. But the policy can |
| 53 |
be changed when the message is serialized using a :mod:`~email.generator`. |
| 54 |
This allows, for example, a generic email message to be parsed from disk, but |
| 55 |
to serialize it using standard SMTP settings when sending it to an email |
| 56 |
server. |
| 57 |
|
| 58 |
The email package does its best to hide the details of the various governing |
| 59 |
RFCs from the application. Conceptually the application should be able to |
| 60 |
treat the email message as a structured tree of unicode text and binary |
| 61 |
attachments, without having to worry about how these are represented when |
| 62 |
serialized. In practice, however, it is often necessary to be aware of at |
| 63 |
least some of the rules governing MIME messages and their structure, |
| 64 |
specifically the names and nature of the MIME "content types" and how they |
| 65 |
identify multipart documents. For the most part this knowledge should only be |
| 66 |
required for more complex applications, and even then it should only be the |
| 67 |
high level structure in question, and not the details of how those structures |
| 68 |
are represented. Since MIME content types are used widely in modern internet |
| 69 |
software (not just email), this will be a familiar concept to many programmers. |
| 70 |
|
| 71 |
The following sections describe the functionality of the :mod:`!email` package. |
| 72 |
We start with the :mod:`~email.message` object model, which is the primary |
| 73 |
interface 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 |
| 76 |
components of the library. |
| 77 |
|
| 78 |
The next three sections cover the exceptions the package may raise and the |
| 79 |
defects (non-compliance with the RFCs) that the :mod:`~email.parser` may |
| 80 |
detect. Then we cover the :mod:`~email.headerregistry` and the |
| 81 |
:mod:`~email.contentmanager` sub-components, which provide tools for doing more |
| 82 |
detailed manipulation of headers and payloads, respectively. Both of these |
| 83 |
components contain features relevant to consuming and producing non-trivial |
| 84 |
messages, but also document their extensibility APIs, which will be of interest |
| 85 |
to advanced applications. |
| 86 |
|
| 87 |
Following those is a set of examples of using the fundamental parts of the APIs |
| 88 |
covered in the preceding sections. |
| 89 |
|
| 90 |
The foregoing represent the modern (unicode friendly) API of the email package. |
| 91 |
The remaining sections, starting with the :class:`~email.message.Message` |
| 92 |
class, cover the legacy :data:`~email.policy.compat32` API that deals much more |
| 93 |
directly 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 |
| 95 |
the application, but for applications that need to operate at that level, they |
| 96 |
can be useful tools. This documentation is also relevant for applications that |
| 97 |
are still using the :mod:`~email.policy.compat32` API for backward |
| 98 |
compatibility 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 |
|
| 105 |
Contents 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 |
|
| 120 |
Legacy 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:`mailbox` |
| 145 |
Tools for creating, reading, and managing collections of messages on disk |
| 146 |
using a variety standard formats. |