imaplib — IMAP4 协议客户端¶
源代码: Lib/imaplib.py
该模块定义了三个类，IMAP4、IMAP4_SSL 和 IMAP4_stream，它们封装了与 IMAP4 服务器的连接，并实现了 RFC 2060 中定义的 IMAP4rev1 客户端协议的大部分子集。它向后兼容 IMAP4 (RFC 1730) 服务器，但请注意，IMAP4 不支持 STATUS 命令。
可用性：不可用于 Emscripten，不可用于 WASI。
此模块在 WebAssembly 平台 wasm32-emscripten 和 wasm32-wasi 上不可用或无法工作。有关更多信息，请参阅 WebAssembly 平台。
- class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶
此类实现了实际的 IMAP4 协议。连接在实例初始化时创建，并确定协议版本（IMAP4 或 IMAP4rev1）。如果未指定 host，则使用
''（本地主机）。如果省略 port，则使用标准 IMAP4 端口（143）。可选的 timeout 参数指定连接尝试的超时时间（以秒为单位）。如果未给出 timeout 或为None，则使用全局默认套接字超时。IMAP4类支持with语句。当像这样使用时，当with语句退出时，会自动发出 IMAP4LOGOUT命令。例如：>>> from imaplib import IMAP4 >>> with IMAP4("domain.org") as M: ... M.noop() ... ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
在 3.5 版更改: 添加了对
with语句的支持。在 3.9 版更改: 添加了可选的 timeout 参数。
三个异常被定义为 IMAP4 类的属性
- exception IMAP4.error¶
在任何错误发生时引发异常。异常原因作为字符串传递给构造函数。
- exception IMAP4.abort¶
IMAP4 服务器错误会导致引发此异常。这是
IMAP4.error的子类。请注意，关闭实例并实例化一个新实例通常可以从该异常中恢复。
- exception IMAP4.readonly¶
当可写邮箱的状态被服务器更改时，会引发此异常。这是
IMAP4.error的子类。现在，其他一些客户端具有写权限，需要重新打开邮箱才能重新获得写权限。
还有一个用于安全连接的子类
- class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)¶
这是从
IMAP4派生的子类，它通过 SSL 加密套接字进行连接（要使用此类，您需要使用 SSL 支持编译的套接字模块）。如果未指定 host，则使用''（本地主机）。如果省略 port，则使用标准的 IMAP4-over-SSL 端口（993）。ssl_context 是一个ssl.SSLContext对象，它允许将 SSL 配置选项、证书和私钥捆绑到一个（可能是长期存在的）结构中。请阅读 安全注意事项 以了解最佳实践。可选的 timeout 参数指定连接尝试的超时时间（以秒为单位）。如果未给出 timeout 或为
None，则使用全局默认套接字超时。在 3.3 版更改: 添加了 ssl_context 参数。
在 3.4 版更改: 该类现在支持使用
ssl.SSLContext.check_hostname和 *服务器名称指示*（请参阅ssl.HAS_SNI）进行主机名检查。在 3.9 版更改: 添加了可选的 timeout 参数。
在 3.12 版更改: 已删除已弃用的 keyfile 和 certfile 参数。
第二个子类允许由子进程创建连接
- class imaplib.IMAP4_stream(command)¶
这是从
IMAP4派生的子类，它连接到通过将 command 传递给subprocess.Popen()创建的stdin/stdout文件描述符。
定义了以下实用函数
- imaplib.Internaldate2tuple(datestr)¶
解析 IMAP4
INTERNALDATE字符串并返回相应的本地时间。返回值是一个time.struct_time元组，如果字符串格式错误，则返回None。
- imaplib.Int2AP(num)¶
使用集合 [
A..P] 中的字符将整数转换为字节表示形式。
- imaplib.ParseFlags(flagstr)¶
将 IMAP4
FLAGS响应转换为单个标志的元组。
- imaplib.Time2Internaldate(date_time)¶
将 date_time 转换为 IMAP4
INTERNALDATE表示形式。返回值是一个字符串，格式为："DD-Mmm-YYYY HH:MM:SS +HHMM"（包括双引号）。date_time 参数可以是表示自纪元以来的秒数（由time.time()返回）的数字（整数或浮点数），表示本地时间的 9 元组，time.struct_time的实例（由time.localtime()返回），datetime.datetime的感知实例或带双引号的字符串。在最后一种情况下，假定它已经是正确的格式。
请注意，IMAP4 消息编号会随着邮箱的变化而变化；特别是，在 EXPUNGE 命令执行删除后，剩余消息将重新编号。因此，强烈建议使用 UID 命令使用 UID。
在模块的末尾，有一个测试部分，其中包含更广泛的使用示例。
另请参阅
描述协议的文档、实现该协议的服务器的源代码，华盛顿大学 IMAP 信息中心的所有文档都可以在（**源代码**）https://github.com/uw-imap/imap（**未维护**）中找到。
IMAP4 对象¶
所有 IMAP4rev1 命令都由相同名称的方法表示，无论是大写还是小写。
命令的所有参数都转换为字符串，但 AUTHENTICATE 和 APPEND 的最后一个参数除外，它们作为 IMAP4 文字传递。如有必要（字符串包含 IMAP4 协议敏感字符，并且未用括号或双引号括起来），则每个字符串都将被引用。但是，LOGIN 命令的 password 参数始终带引号。如果要避免引用参数字符串（例如：STORE 的 flags 参数），请将字符串括在括号中（例如：r'(\Deleted)'）。
每个命令都返回一个元组：(type, [data, ...])，其中 type 通常是 'OK' 或 'NO'，data 是命令响应中的文本或命令的强制结果。每个 data 都是 bytes 或元组。如果是元组，则第一部分是响应的标头，第二部分包含数据（即：“文字”值）。
下面命令的 message_set 选项是一个字符串，用于指定要对其执行操作的一条或多条消息。它可以是简单的消息编号（'1'）、消息编号范围（'2:4'）或一组以逗号分隔的非连续范围（'1:3,6:9'）。范围可以包含星号以指示无限上限（'3:*'）。
IMAP4 实例具有以下方法
- IMAP4.append(mailbox, flags, date_time, message)¶
将 message 追加到指定的邮箱。
- IMAP4.authenticate(mechanism, authobject)¶
身份验证命令 - 需要响应处理。
mechanism 指定要使用的身份验证机制 - 它应该以
AUTH=mechanism的形式出现在实例变量capabilities中。authobject 必须是可调用对象
data = authobject(response)
它将被调用以处理服务器继续响应；传递给它的 response 参数将是
bytes。它应该返回将进行 base64 编码并发送到服务器的bytesdata。如果应该发送客户端中止响应*，则它应该返回None。在 3.5 版更改: 字符串用户名和密码现在编码为
utf-8，而不是限制为 ASCII。
- IMAP4.check()¶
检查服务器上的邮箱。
- IMAP4.close()¶
关闭当前选定的邮箱。已删除的邮件将从可写邮箱中删除。这是
LOGOUT之前的推荐命令。
- IMAP4.copy(message_set, new_mailbox)¶
将 message_set 中的邮件复制到 new_mailbox 的末尾。
- IMAP4.create(mailbox)¶
创建名为 mailbox 的新邮箱。
- IMAP4.delete(mailbox)¶
删除名为 mailbox 的旧邮箱。
- IMAP4.deleteacl(mailbox, who)¶
删除为 who 在 mailbox 上设置的 ACL（删除任何权限）。
- IMAP4.expunge()¶
从选定的邮箱中永久删除已删除的项目。为每个已删除的邮件生成一个
EXPUNGE响应。返回的数据包含按接收顺序排列的EXPUNGE邮件编号列表。
- IMAP4.fetch(message_set, message_parts)¶
获取邮件（的部分内容）。message_parts 应为括在括号内的邮件部分名称字符串，例如：
"(UID BODY[TEXT])"。返回的数据是邮件部分信封和数据的元组。
- IMAP4.getacl(mailbox)¶
获取 mailbox 的
ACL。该方法是非标准的，但受Cyrus服务器支持。
- IMAP4.getannotation(mailbox, entry, attribute)¶
检索 mailbox 的指定
ANNOTATION。该方法是非标准的，但受Cyrus服务器支持。
- IMAP4.getquota(root)¶
获取
quotaroot 的资源使用情况和限制。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。
- IMAP4.getquotaroot(mailbox)¶
获取名为 mailbox 的邮箱的
quotaroots列表。此方法是 rfc2087 中定义的 IMAP4 QUOTA 扩展的一部分。
- IMAP4.list([directory[, pattern]])¶
列出 directory 中与 pattern 匹配的邮箱名称。directory 默认为顶级邮件文件夹，pattern 默认为匹配任何内容。返回的数据包含
LIST响应列表。
- IMAP4.login(user, password)¶
使用明文密码标识客户端。password 将被引用。
- IMAP4.login_cram_md5(user, password)¶
在标识客户端以保护密码时强制使用
CRAM-MD5身份验证。仅在服务器CAPABILITY响应包含短语AUTH=CRAM-MD5时才有效。
- IMAP4.logout()¶
断开与服务器的连接。返回服务器
BYE响应。在 3.8 版更改: 该方法不再静默忽略任意异常。
- IMAP4.lsub(directory='""', pattern='*')¶
列出目录中与模式匹配的已订阅邮箱名称。directory 默认为顶级目录，pattern 默认为匹配任何邮箱。返回的数据是邮件部分信封和数据的元组。
- IMAP4.myrights(mailbox)¶
显示我对邮箱的 ACL（即我对邮箱拥有的权限）。
- IMAP4.noop()¶
向服务器发送
NOOP。
- IMAP4.open(host, port, timeout=None)¶
在host的port端口打开套接字。可选的timeout参数指定连接尝试的超时时间（以秒为单位）。如果未给出timeout或为
None，则使用全局默认套接字超时。另请注意，如果将timeout参数设置为零，则会引发ValueError以拒绝创建非阻塞套接字。此方法由IMAP4构造函数隐式调用。由此方法建立的连接对象将用于IMAP4.read()、IMAP4.readline()、IMAP4.send()和IMAP4.shutdown()方法中。您可以覆盖此方法。引发带有参数
self、host、port的审计事件imaplib.open。在 3.9 版更改: 添加了timeout参数。
- IMAP4.partial(message_num, message_part, start, length)¶
获取邮件的截断部分。返回的数据是一个元组，包含邮件部分信封和数据。
- IMAP4.proxyauth(user)¶
假定以user身份进行身份验证。允许授权管理员代理到任何用户的邮箱。
- IMAP4.read(size)¶
从远程服务器读取size字节的数据。您可以覆盖此方法。
- IMAP4.readline()¶
从远程服务器读取一行。您可以覆盖此方法。
- IMAP4.recent()¶
提示服务器进行更新。如果没有新消息，则返回数据为
None，否则为RECENT响应的值。
- IMAP4.rename(oldmailbox, newmailbox)¶
将名为oldmailbox的邮箱重命名为newmailbox。
- IMAP4.response(code)¶
如果收到响应代码code，则返回其数据，否则返回
None。返回给定的代码，而不是通常的类型。
- IMAP4.search(charset, criterion[, ...])¶
在邮箱中搜索匹配的邮件。charset可以是
None，在这种情况下，在对服务器的请求中不会指定CHARSET。IMAP协议要求至少指定一个条件；当服务器返回错误时，将引发异常。如果使用enable()命令启用了UTF8=ACCEPT功能，则charset必须为None。示例
# M is a connected IMAP4 instance... typ, msgnums = M.search(None, 'FROM', '"LDJ"') # or: typ, msgnums = M.search(None, '(FROM "LDJ")')
- IMAP4.select(mailbox='INBOX', readonly=False)¶
选择一个邮箱。返回的数据是mailbox中邮件的数量（
EXISTS响应）。默认的mailbox是'INBOX'。如果设置了readonly标志，则不允许修改邮箱。
- IMAP4.setacl(mailbox, who, what)¶
为mailbox设置
ACL。该方法是非标准的，但受Cyrus服务器支持。
- IMAP4.setannotation(mailbox, entry, attribute[, ...])¶
为mailbox设置
ANNOTATION。该方法是非标准的，但受Cyrus服务器支持。
- IMAP4.setquota(root, limits)¶
设置
quotaroot的资源limits。此方法是rfc2087中定义的IMAP4 QUOTA扩展的一部分。
- IMAP4.shutdown()¶
关闭在
open中建立的连接。此方法由IMAP4.logout()隐式调用。您可以覆盖此方法。
- IMAP4.socket()¶
返回用于连接服务器的套接字实例。
- IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶
sort命令是search的一种变体，具有对结果进行排序的语义。返回的数据包含以空格分隔的匹配邮件编号列表。在 search_criterion 参数之前，Sort 有两个参数：一个带括号的 sort_criteria 列表和搜索 charset。请注意，与
search不同，搜索 charset 参数是必需的。还有一个uid sort命令，它对应于sort，就像uid search对应于search一样。sort命令首先使用 charset 参数解释搜索条件中的字符串，在邮箱中搜索与给定搜索条件匹配的邮件。然后，它返回匹配邮件的编号。这是一个
IMAP4rev1扩展命令。
- IMAP4.starttls(ssl_context=None)¶
发送
STARTTLS命令。ssl_context 参数是可选的，应该是一个ssl.SSLContext对象。这将启用 IMAP 连接上的加密。有关最佳实践，请阅读 安全注意事项。3.2 版新增。
在 3.4 版更改: 该方法现在支持使用
ssl.SSLContext.check_hostname和 *服务器名称指示* 进行主机名检查（请参阅ssl.HAS_SNI）。
- IMAP4.status(mailbox, names)¶
请求 mailbox 的命名状态条件。
- IMAP4.store(message_set, command, flag_list)¶
更改邮箱中邮件的标志处置。RFC 2060 第 6.4.6 节将 command 指定为 “FLAGS”、“+FLAGS” 或 “-FLAGS” 之一，可选后缀为 “.SILENT”。
例如，要设置所有邮件的删除标志
typ, data = M.search(None, 'ALL') for num in data[0].split(): M.store(num, '+FLAGS', '\\Deleted') M.expunge()
注意
创建包含“]”的标志（例如：“[test]”）违反了RFC 3501（IMAP 协议）。但是，imaplib 过去一直允许创建此类标签，并且流行的 IMAP 服务器（例如 Gmail）接受并生成此类标志。也有一些非 Python 程序会创建此类标签。尽管这违反了 RFC 并且 IMAP 客户端和服务器应该严格遵守，但为了向后兼容，imaplib 仍然允许创建此类标签，并且从 Python 3.6 开始，如果服务器发送了此类标签，它会对其进行处理，因为这提高了现实世界的兼容性。
- IMAP4.subscribe(mailbox)¶
订阅新邮箱。
- IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])¶
thread命令是search的一种变体，具有对结果进行线程化的语义。返回的数据包含以空格分隔的线程成员列表。线程成员由零个或多个邮件编号组成，以空格分隔，表示连续的父级和子级。
在 search_criterion 参数之前，Thread 有两个参数：threading_algorithm 和搜索 charset。请注意，与
search不同，搜索 charset 参数是必需的。还有一个uid thread命令，它对应于thread，就像uid search对应于search一样。thread命令首先使用 charset 参数解释搜索条件中的字符串，在邮箱中搜索与给定搜索条件匹配的邮件。然后，它根据指定的线程算法返回匹配的邮件线程。这是一个
IMAP4rev1扩展命令。
- IMAP4.uid(command, arg[, ...])¶
使用 UID 而不是邮件编号标识的邮件执行命令参数。返回适合命令的响应。必须至少提供一个参数；如果没有提供，服务器将返回错误并引发异常。
- IMAP4.unsubscribe(mailbox)¶
取消订阅旧邮箱。
- IMAP4.unselect()¶
imaplib.IMAP4.unselect()释放与所选邮箱关联的服务器资源，并将服务器返回到已验证状态。此命令执行与imaplib.IMAP4.close()相同的操作，但不会从当前选择的邮箱中永久删除任何邮件。3.9 版新增。
- IMAP4.xatom(name[, ...])¶
允许在
CAPABILITY响应中由服务器通知的简单扩展命令。
以下属性在 IMAP4 的实例上定义
- IMAP4.PROTOCOL_VERSION¶
服务器
CAPABILITY响应中最新的受支持协议。
- IMAP4.debug¶
控制调试输出的整数值。初始值取自模块变量
Debug。大于三的值将跟踪每个命令。
IMAP4 示例¶
这是一个最小的示例（没有错误检查），它打开一个邮箱并检索并打印所有邮件
import getpass, imaplib
M = imaplib.IMAP4(host='example.org')
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
typ, data = M.fetch(num, '(RFC822)')
print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()