email — An email and MIME handling package电子邮件和MIME处理包

Source code: Lib/email/__init__.py

The email package is a library for managing email messages. It is specifically not designed to do any sending of email messages to SMTP (RFC 2821), NNTP, or other servers; those are functions of modules such as smtplib and nntplib. The email package attempts to be as RFC-compliant as possible, supporting RFC 5322 and RFC 6532, as well as such MIME-related RFCs as RFC 2045, RFC 2046, RFC 2047, RFC 2183, and RFC 2231.

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.电子邮件包的整体结构可分为三个主要组件，外加控制其他组件行为的第四个组件。

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 message sub-module. 应用程序主要通过message子模块中定义的对象模型接口与包进行交互。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. 应用程序可以使用此API询问有关现有电子邮件的问题，构造新电子邮件，或者添加或删除本身使用相同对象模型接口的电子邮件子组件。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 EmailMessage API.也就是说，根据电子邮件及其MIME子组件的性质，电子邮件对象模型是一个对象树结构，所有对象都提供了EmailMessage API。

The other two major components of the package are the parser and the generator. The parser takes the serialized version of an email message (a stream of bytes) and converts it into a tree of EmailMessage objects. The generator takes an EmailMessage 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.)（解析器和生成器也处理文本字符流，但不鼓励这种用法，因为它太容易以某种方式无效的消息结束。）

The control component is the policy module. Every EmailMessage, every generator, and every parser has an associated policy object that controls its behavior. Usually an application only needs to specify the policy when an EmailMessage is created, either by directly instantiating an EmailMessage to create a new email, or by parsing an input stream using a parser. But the policy can be changed when the message is serialized using a generator. 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.例如，这允许从磁盘解析通用电子邮件，但在将其发送到电子邮件服务器时使用标准SMTP设置将其序列化。

The email package does its best to hide the details of the various governing RFCs from the application. 电子邮件包尽最大努力向应用程序隐藏各种管理RFC的详细信息。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. 从概念上讲，应用程序应该能够将电子邮件消息视为unicode文本和二进制附件的结构化树，而不必担心序列化时如何表示它们。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. 然而，在实践中，通常需要了解至少一些管理MIME消息及其结构的规则，特别是MIME“内容类型”的名称和性质，以及它们如何识别多部分文档。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.由于MIME内容类型广泛应用于现代互联网软件（不仅仅是电子邮件），这将是许多程序员熟悉的概念。

The following sections describe the functionality of the email package. We start with the message object model, which is the primary interface an application will use, and follow that with the parser and generator components. Then we cover the policy controls, which completes the treatment of the main components of the library.

The next three sections cover the exceptions the package may raise and the defects (non-compliance with the RFCs) that the parser may detect. 接下来的三节将介绍包可能引发的异常以及parser可能检测到的缺陷（不符合RFC）。Then we cover the headerregistry and the contentmanager 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.这两个组件都包含与消费和生成非平凡消息相关的功能，但也记录了它们的可扩展性API，这对高级应用程序很有意义。

Following those is a set of examples of using the fundamental parts of the APIs covered in the preceding sections.下面是一组使用前面几节中介绍的API基本部分的示例。

The foregoing represent the modern (unicode friendly) API of the email package. 上述内容代表了电子邮件包的现代（unicode友好）API。The remaining sections, starting with the Message class, cover the legacy compat32 API that deals much more directly with the details of how email messages are represented. The compat32 API does not 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 compat32 API for backward compatibility reasons.

Changed in version 3.6:版本3.6中更改： Docs reorganized and rewritten to promote the new EmailMessage/EmailPolicy API.

Contents of the email package documentation:

Legacy API:

See also

Module smtplib

SMTP (Simple Mail Transport Protocol) client

Module poplib

POP (Post Office Protocol) client

Module imaplib

IMAP (Internet Message Access Protocol) client

Module nntplib

NNTP (Net News Transport Protocol) client

Module mailbox

Tools for creating, reading, and managing collections of messages on disk using a variety standard formats.

Module smtpd

SMTP server framework (primarily useful for testing)