1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
|
<span id="email-an-email-and-mime-handling-package"></span><h1>email — An email and MIME handling package</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/email/__init__.py">Lib/email/__init__.py</a></p> <p>The <a class="reference internal" href="#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code>email</code></a> package is a library for managing email messages. It is specifically <em>not</em> designed to do any sending of email messages to SMTP (<span class="target" id="index-0"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2821.html"><strong>RFC 2821</strong></a>), NNTP, or other servers; those are functions of modules such as <a class="reference internal" href="smtplib#module-smtplib" title="smtplib: SMTP protocol client (requires sockets)."><code>smtplib</code></a> and <a class="reference internal" href="nntplib#module-nntplib" title="nntplib: NNTP protocol client (requires sockets). (deprecated)"><code>nntplib</code></a>. The <a class="reference internal" href="#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code>email</code></a> package attempts to be as RFC-compliant as possible, supporting <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc5322.html"><strong>RFC 5322</strong></a> and <span class="target" id="index-2"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc6532.html"><strong>RFC 6532</strong></a>, as well as such MIME-related RFCs as <span class="target" id="index-3"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2045.html"><strong>RFC 2045</strong></a>, <span class="target" id="index-4"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2046.html"><strong>RFC 2046</strong></a>, <span class="target" id="index-5"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2047.html"><strong>RFC 2047</strong></a>, <span class="target" id="index-6"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2183.html"><strong>RFC 2183</strong></a>, and <span class="target" id="index-7"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc2231.html"><strong>RFC 2231</strong></a>.</p> <p>The overall structure of the email package can be divided into three major components, plus a fourth component that controls the behavior of the other components.</p> <p>The central component of the package is an “object model” that represents email messages. An application interacts with the package primarily through the object model interface defined in the <a class="reference internal" href="email.message#module-email.message" title="email.message: The base class representing email messages."><code>message</code></a> sub-module. The application can use this API to ask questions about an existing email, to construct a new email, or to add or remove email subcomponents that themselves use the same object model interface. That is, following the nature of email messages and their MIME subcomponents, the email object model is a tree structure of objects that all provide the <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a> API.</p> <p>The other two major components of the package are the <a class="reference internal" href="email.parser#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code>parser</code></a> and the <a class="reference internal" href="email.generator#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code>generator</code></a>. The parser takes the serialized version of an email message (a stream of bytes) and converts it into a tree of <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a> objects. The generator takes an <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a> and turns it back into a serialized byte stream. (The parser and generator also handle streams of text characters, but this usage is discouraged as it is too easy to end up with messages that are not valid in one way or another.)</p> <p>The control component is the <a class="reference internal" href="email.policy#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code>policy</code></a> module. Every <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a>, every <a class="reference internal" href="email.generator#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code>generator</code></a>, and every <a class="reference internal" href="email.parser#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code>parser</code></a> has an associated <a class="reference internal" href="email.policy#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code>policy</code></a> object that controls its behavior. Usually an application only needs to specify the policy when an <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a> is created, either by directly instantiating an <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a> to create a new email, or by parsing an input stream using a <a class="reference internal" href="email.parser#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code>parser</code></a>. But the policy can be changed when the message is serialized using a <a class="reference internal" href="email.generator#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code>generator</code></a>. This allows, for example, a generic email message to be parsed from disk, but to serialize it using standard SMTP settings when sending it to an email server.</p> <p>The email package does its best to hide the details of the various governing RFCs from the application. Conceptually the application should be able to treat the email message as a structured tree of unicode text and binary attachments, without having to worry about how these are represented when serialized. In practice, however, it is often necessary to be aware of at least some of the rules governing MIME messages and their structure, specifically the names and nature of the MIME “content types” and how they identify multipart documents. For the most part this knowledge should only be required for more complex applications, and even then it should only be the high level structure in question, and not the details of how those structures are represented. Since MIME content types are used widely in modern internet software (not just email), this will be a familiar concept to many programmers.</p> <p>The following sections describe the functionality of the <a class="reference internal" href="#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code>email</code></a> package. We start with the <a class="reference internal" href="email.message#module-email.message" title="email.message: The base class representing email messages."><code>message</code></a> object model, which is the primary interface an application will use, and follow that with the <a class="reference internal" href="email.parser#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code>parser</code></a> and <a class="reference internal" href="email.generator#module-email.generator" title="email.generator: Generate flat text email messages from a message structure."><code>generator</code></a> components. Then we cover the <a class="reference internal" href="email.policy#module-email.policy" title="email.policy: Controlling the parsing and generating of messages"><code>policy</code></a> controls, which completes the treatment of the main components of the library.</p> <p>The next three sections cover the exceptions the package may raise and the defects (non-compliance with the RFCs) that the <a class="reference internal" href="email.parser#module-email.parser" title="email.parser: Parse flat text email messages to produce a message object structure."><code>parser</code></a> may detect. Then we cover the <a class="reference internal" href="email.headerregistry#module-email.headerregistry" title="email.headerregistry: Automatic Parsing of headers based on the field name"><code>headerregistry</code></a> and the <a class="reference internal" href="email.contentmanager#module-email.contentmanager" title="email.contentmanager: Storing and Retrieving Content from MIME Parts"><code>contentmanager</code></a> sub-components, which provide tools for doing more detailed manipulation of headers and payloads, respectively. Both of these components contain features relevant to consuming and producing non-trivial messages, but also document their extensibility APIs, which will be of interest to advanced applications.</p> <p>Following those is a set of examples of using the fundamental parts of the APIs covered in the preceding sections.</p> <p>The foregoing represent the modern (unicode friendly) API of the email package. The remaining sections, starting with the <a class="reference internal" href="email.compat32-message#email.message.Message" title="email.message.Message"><code>Message</code></a> class, cover the legacy <a class="reference internal" href="email.policy#email.policy.compat32" title="email.policy.compat32"><code>compat32</code></a> API that deals much more directly with the details of how email messages are represented. The <a class="reference internal" href="email.policy#email.policy.compat32" title="email.policy.compat32"><code>compat32</code></a> API does <em>not</em> hide the details of the RFCs from the application, but for applications that need to operate at that level, they can be useful tools. This documentation is also relevant for applications that are still using the <a class="reference internal" href="email.policy#email.policy.compat32" title="email.policy.compat32"><code>compat32</code></a> API for backward compatibility reasons.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Docs reorganized and rewritten to promote the new <a class="reference internal" href="email.message#email.message.EmailMessage" title="email.message.EmailMessage"><code>EmailMessage</code></a>/<a class="reference internal" href="email.policy#email.policy.EmailPolicy" title="email.policy.EmailPolicy"><code>EmailPolicy</code></a> API.</p> </div> <p>Contents of the <a class="reference internal" href="#module-email" title="email: Package supporting the parsing, manipulating, and generating email messages."><code>email</code></a> package documentation:</p> <ul> <li class="toctree-l1"><a class="reference internal" href="email.message"><code>email.message</code>: Representing an email message</a></li> <li class="toctree-l1">
<a class="reference internal" href="email.parser"><code>email.parser</code>: Parsing email messages</a><ul> <li class="toctree-l2"><a class="reference internal" href="email.parser#feedparser-api">FeedParser API</a></li> <li class="toctree-l2"><a class="reference internal" href="email.parser#parser-api">Parser API</a></li> <li class="toctree-l2"><a class="reference internal" href="email.parser#additional-notes">Additional notes</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="email.generator"><code>email.generator</code>: Generating MIME documents</a></li> <li class="toctree-l1"><a class="reference internal" href="email.policy"><code>email.policy</code>: Policy Objects</a></li> <li class="toctree-l1"><a class="reference internal" href="email.errors"><code>email.errors</code>: Exception and Defect classes</a></li> <li class="toctree-l1"><a class="reference internal" href="email.headerregistry"><code>email.headerregistry</code>: Custom Header Objects</a></li> <li class="toctree-l1">
<a class="reference internal" href="email.contentmanager"><code>email.contentmanager</code>: Managing MIME Content</a><ul> <li class="toctree-l2"><a class="reference internal" href="email.contentmanager#content-manager-instances">Content Manager Instances</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="email.examples"><code>email</code>: Examples</a></li> </ul> <p>Legacy API:</p> <ul> <li class="toctree-l1"><a class="reference internal" href="email.compat32-message"><code>email.message.Message</code>: Representing an email message using the <code>compat32</code> API</a></li> <li class="toctree-l1"><a class="reference internal" href="email.mime"><code>email.mime</code>: Creating email and MIME objects from scratch</a></li> <li class="toctree-l1"><a class="reference internal" href="email.header"><code>email.header</code>: Internationalized headers</a></li> <li class="toctree-l1"><a class="reference internal" href="email.charset"><code>email.charset</code>: Representing character sets</a></li> <li class="toctree-l1"><a class="reference internal" href="email.encoders"><code>email.encoders</code>: Encoders</a></li> <li class="toctree-l1"><a class="reference internal" href="email.utils"><code>email.utils</code>: Miscellaneous utilities</a></li> <li class="toctree-l1"><a class="reference internal" href="email.iterators"><code>email.iterators</code>: Iterators</a></li> </ul> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
<code>Module</code> <a class="reference internal" href="smtplib#module-smtplib" title="smtplib: SMTP protocol client (requires sockets)."><code>smtplib</code></a>
</dt>
<dd>
<p>SMTP (Simple Mail Transport Protocol) client</p> </dd> <dt>
<code>Module</code> <a class="reference internal" href="poplib#module-poplib" title="poplib: POP3 protocol client (requires sockets)."><code>poplib</code></a>
</dt>
<dd>
<p>POP (Post Office Protocol) client</p> </dd> <dt>
<code>Module</code> <a class="reference internal" href="imaplib#module-imaplib" title="imaplib: IMAP4 protocol client (requires sockets)."><code>imaplib</code></a>
</dt>
<dd>
<p>IMAP (Internet Message Access Protocol) client</p> </dd> <dt>
<code>Module</code> <a class="reference internal" href="nntplib#module-nntplib" title="nntplib: NNTP protocol client (requires sockets). (deprecated)"><code>nntplib</code></a>
</dt>
<dd>
<p>NNTP (Net News Transport Protocol) client</p> </dd> <dt>
<code>Module</code> <a class="reference internal" href="mailbox#module-mailbox" title="mailbox: Manipulate mailboxes in various formats"><code>mailbox</code></a>
</dt>
<dd>
<p>Tools for creating, reading, and managing collections of messages on disk using a variety standard formats.</p> </dd> </dl> </div> <div class="_attribution">
<p class="_attribution-p">
© 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br>
<a href="https://docs.python.org/3.12/library/email.html" class="_attribution-link">https://docs.python.org/3.12/library/email.html</a>
</p>
</div>
|
