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 (a] python.org>, 8 R. David Murray <rdmurray (a] bitdance.com> 9 .. sectionauthor:: R. David Murray <rdmurray (a] bitdance.com> 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` 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`. 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 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. 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.util.rst 130 email.iterators.rst 131 132 133 .. seealso:: 134 135 Module :mod:`smtplib` 136 SMTP (Simple Mail Transport Protcol) 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
