Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`email` --- An email and MIME handling package |
| 2 | =================================================== |
| 3 | |
| 4 | .. module:: email |
Georg Brandl | 3f076d8 | 2009-05-17 11:28:33 +0000 | [diff] [blame] | 5 | :synopsis: Package supporting the parsing, manipulating, and generating |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 10 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 11 | **Source code:** :source:`Lib/email/__init__.py` |
| 12 | |
| 13 | -------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 14 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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` and :mod:`nntplib`. The :mod:`email` package attempts to be as |
| 19 | RFC-compliant as possible, supporting :rfc:`5233` and :rfc:`6532`, as well as |
| 20 | such MIME-related RFCs as :rfc:`2045`, :rfc:`2046`, :rfc:`2047`, :rfc:`2183`, |
| 21 | and :rfc:`2231`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 22 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 70 | |
| 71 | The following sections describe the functionality of the :mod:`email` package. |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 77 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 86 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 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 forgoing 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 99 | |
R David Murray | 7f730cf | 2016-09-08 18:28:43 -0400 | [diff] [blame] | 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 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | Contents of the :mod:`email` package documentation: |
| 106 | |
| 107 | .. toctree:: |
| 108 | |
| 109 | email.message.rst |
| 110 | email.parser.rst |
| 111 | email.generator.rst |
Georg Brandl | e8d2d2d | 2011-04-19 09:21:00 +0200 | [diff] [blame] | 112 | email.policy.rst |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 113 | |
| 114 | email.errors.rst |
R David Murray | 79cf3ba | 2012-05-27 17:10:36 -0400 | [diff] [blame] | 115 | email.headerregistry.rst |
R David Murray | 3da240f | 2013-10-16 22:48:40 -0400 | [diff] [blame] | 116 | email.contentmanager.rst |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 117 | |
| 118 | email.examples.rst |
| 119 | |
R David Murray | 7f730cf | 2016-09-08 18:28:43 -0400 | [diff] [blame] | 120 | Legacy API: |
| 121 | |
| 122 | .. toctree:: |
| 123 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 124 | email.compat32-message.rst |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | email.mime.rst |
| 126 | email.header.rst |
| 127 | email.charset.rst |
| 128 | email.encoders.rst |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 129 | email.util.rst |
| 130 | email.iterators.rst |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 131 | |
| 132 | |
| 133 | .. seealso:: |
| 134 | |
| 135 | Module :mod:`smtplib` |
Xtreak | c151f78 | 2018-06-16 10:38:31 +0530 | [diff] [blame] | 136 | SMTP (Simple Mail Transport Protocol) client |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 137 | |
| 138 | Module :mod:`poplib` |
| 139 | POP (Post Office Protocol) client |
| 140 | |
| 141 | Module :mod:`imaplib` |
| 142 | IMAP (Internet Message Access Protocol) client |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 143 | |
| 144 | Module :mod:`nntplib` |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 145 | NNTP (Net News Transport Protocol) client |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 146 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 147 | Module :mod:`mailbox` |
| 148 | Tools for creating, reading, and managing collections of messages on disk |
| 149 | using a variety standard formats. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 150 | |
R David Murray | 29d1bc0 | 2016-09-07 21:15:59 -0400 | [diff] [blame] | 151 | Module :mod:`smtpd` |
| 152 | SMTP server framework (primarily useful for testing) |