imaplib — IMAP4 協議客戶端¶
原始碼： Lib/imaplib.py
此模組定義了三個類，IMAP4、IMAP4_SSL 和 IMAP4_stream，它們封裝了到 IMAP4 伺服器的連線，並實現了 RFC 2060 中定義的 IMAP4rev1 客戶端協議的很大一部分子集。它向後相容 IMAP4 (RFC 1730) 伺服器，但請注意 STATUS 命令在 IMAP4 中不受支援。
可用性：不是 WASI。
此模組在 WebAssembly 上不起作用或不可用。有關更多資訊，請參閱 WebAssembly 平臺。
- class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶
此類實現了實際的 IMAP4 協議。當例項初始化時，將建立連線並確定協議版本（IMAP4 或 IMAP4rev1）。如果未指定 host，則使用
''（本地主機）。如果省略 port，則使用標準 IMAP4 埠 (143)。可選的 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 引數指定連線嘗試的超時時間（以秒為單位）。如果未給定超時時間或為
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 引數可以是表示自 epoch 以來的秒數的數字（int 或 float）（如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 附加到名為 mailbox 的郵箱。
- IMAP4.authenticate(mechanism, authobject)¶
驗證命令 — 需要響應處理。
mechanism 指定要使用的身份驗證機制 - 它應以
AUTH=mechanism的形式出現在例項變數capabilities中。authobject 必須是可呼叫物件
data = authobject(response)
將呼叫它來處理伺服器的延續響應；傳遞給它的 response 引數將是
bytes。它應返回bytesdata，該 data 將被 base64 編碼併發送到伺服器。如果應改為傳送客戶端中止響應*，則應返回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 設定的 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)¶
獲取 root 的資源使用情況和限制的
quota。此方法是 rfc2087 中定義的 IMAP4 QUOTA 擴充套件的一部分。
- IMAP4.getquotaroot(mailbox)¶
獲取名為 mailbox 的
quotaroots列表。此方法是 rfc2087 中定義的 IMAP4 QUOTA 擴充套件的一部分。
- IMAP4.list([directory[, pattern]])¶
列出與 pattern 匹配的 directory 中的郵箱名稱。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 引數指定連線嘗試的超時時間（以秒為單位）。如果未給定超時或超時為
None，則使用全域性預設套接字超時。另請注意，如果將 timeout 引數設定為零，它將引發ValueError以拒絕建立非阻塞套接字。此方法由IMAP4建構函式隱式呼叫。此方法建立的連線物件將用於IMAP4.read()、IMAP4.readline()、IMAP4.send()和IMAP4.shutdown()方法。您可以覆蓋此方法。引發一個 審計事件
imaplib.open，引數為self、host、port。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)¶
設定 root 的資源 limits 的
quota。此方法是 rfc2087 中定義的 IMAP4 QUOTA 擴充套件的一部分。
- IMAP4.shutdown()¶
關閉在
open中建立的連線。此方法由IMAP4.logout()隱式呼叫。您可以覆蓋此方法。
- IMAP4.socket()¶
返回用於連線到伺服器的套接字例項。
- IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶
sort命令是search的變體，對結果具有排序語義。返回的資料包含一個以空格分隔的匹配訊息編號列表。Sort 在 search_criterion 引數之前有兩個引數；一個包含在括號中的 sort_criteria 列表和一個搜尋 charset。請注意，與
search不同，搜尋 charset 引數是強制性的。還有一個uid sort命令，它對應於sort，就像uid search對應於search一樣。sort命令首先使用字元集引數解釋搜尋條件中的字串，在郵箱中搜索與給定搜尋條件匹配的訊息。然後返回匹配的訊息編號。這是一個
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)¶
更改郵箱中訊息的標誌處理。command 由 RFC 2060 的 6.4.6 節指定為 “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的一個變體，它為結果提供執行緒語義。返回的資料包含一個以空格分隔的執行緒成員列表。執行緒成員由零個或多個訊息編號組成，以空格分隔，表示連續的父訊息和子訊息。
thread命令在 search_criterion 引數之前有兩個引數：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。大於 3 的值會跟蹤每個命令。
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()