imaplib --- IMAP4 協議客戶端¶
原始碼： Lib/imaplib.py
此模組定義了三個類 IMAP4、IMAP4_SSL 和 IMAP4_stream，它們封裝了與 IMAP4 伺服器的連線，並實現了 RFC 2060 中定義的大部分 IMAP4rev1 客戶端協議。它向後相容 IMAP4 (RFC 1730) 伺服器，但請注意 IMAP4 不支援 STATUS 命令。
可用性：非 WASI。
此模組在 WebAssembly 上不起作用或不可用。有關更多資訊，請參閱 WebAssembly 平臺。
- class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶
該類實現了實際的 IMAP4 協議。在例項初始化時建立連線並確定協議版本（IMAP4 或 IMAP4rev1）。如果未指定 host，則使用
''（本地主機）。如果省略 port，則使用標準的 IMAP4 埠（143）。可選的 timeout 引數指定連線嘗試的超時時間（以秒為單位）。如果未給出 timeout 或其值為None，則使用全域性預設套接字超時時間。IMAP4類支援with語句。這樣使用時，IMAP4 的LOGOUT命令會在with語句退出時自動發出。例如：>>> 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 支援的 socket 模組）。如果未指定 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 指定要使用的認證機制——它應出現在例項變數
capabilities中，形式為AUTH=mechanism。authobject 必須是一個可呼叫物件：
data = authobject(response)
它將被呼叫以處理伺服器的繼續響應；傳遞給它的 response 引數將是
bytes。它應該返回bytes型別的 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 在 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 的指定
ANNOTATIONs。該方法非標準，但Cyrus伺服器支援。
- IMAP4.getquota(root)¶
獲取
quotaroot 的資源使用情況和限制。該方法是 rfc2087 中定義的 IMAP4 QUOTA 擴充套件的一部分。
- IMAP4.getquotaroot(mailbox)¶
獲取指定 mailbox 的
quotaroots列表。該方法是 rfc2087 中定義的 IMAP4 QUOTA 擴充套件的一部分。
- IMAP4.idle(duration=None)¶
返回一個
Idler：一個可迭代的上下文管理器，實現了 RFC 2177 中定義的 IMAP4IDLE命令。返回的物件在被
with語句啟用時傳送IDLE命令，透過 迭代器 協議產生 IMAP 未標記響應，並在上下文退出時傳送DONE。所有在傳送
IDLE命令後到達的未標記響應（包括在伺服器確認該命令之前到達的任何響應）都可以透過迭代獲得。任何剩餘的響應（那些在with上下文中未迭代的響應）可以在IDLE結束後透過IMAP4.response()以常規方式檢索。響應表示為
(type, [data, ...])元組，如 IMAP4 Objects 中所述。duration 引數設定一個最大空閒持續時間（以秒為單位），超過該時間後任何正在進行的迭代將停止。它可以是
int或float，或者None表示沒有時間限制。希望避免在施加不活動超時的伺服器上超時的呼叫者應將其保持在最多 29 分鐘（1740 秒）。需要套接字連線；在IMAP4_stream連線上，duration 必須為None。>>> with M.idle(duration=29 * 60) as idler: ... for typ, data in idler: ... print(typ, data) ... EXISTS [b'1'] RECENT [b'1']
- Idler.burst(interval=0.1)¶
產生一組響應，這些響應的間隔不超過 interval 秒（表示為
int或float）。這個 生成器 是逐個迭代響應的替代方案，旨在幫助高效的批處理。它檢索下一個響應以及任何立即可用的後續響應。（例如，在批次刪除後快速出現的一系列
EXPUNGE響應。）需要套接字連線；在
IMAP4_stream連線上不起作用。>>> with M.idle() as idler: ... # get a response and any others following by < 0.1 seconds ... batch = list(idler.burst()) ... print(f'processing {len(batch)} responses...') ... print(batch) ... processing 3 responses... [('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]
提示
在等待一批響應中的第一個響應時，會遵守傳遞給
IMAP4.idle()的IDLE上下文的最大持續時間。因此，一個已過期的Idler將導致此生成器立即返回而不產生任何內容。如果在迴圈中使用它，呼叫者應考慮這一點。
備註
IMAP4.idle()返回的迭代器只能在with語句中使用。在該上下文之前或之後，每當命令完成時，未經請求的響應會在內部收集，並可以使用IMAP4.response()檢索。備註
Idler類名和結構是內部介面，可能會發生變化。呼叫程式碼可以依賴於其上下文管理、迭代和公共方法的穩定性，但不應子類化、例項化、比較或以其他方式直接引用該類。在 3.14 版本加入。
- 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時才有效。在 3.14 版更改: 如果 MD5 支援不可用，則會引發
IMAP4.error。
- IMAP4.logout()¶
關閉與伺服器的連線。返回伺服器的
BYE響應。在 3.8 版更改: 該方法不再靜默地忽略任意異常。
- IMAP4.lsub(directory='""', pattern='*')¶
列出目錄中與模式匹配的已訂閱郵箱名稱。*directory* 預設為頂級目錄，*pattern* 預設為匹配任何郵箱。返回的資料是訊息部分信封和資料的元組。
- IMAP4.myrights(mailbox)¶
顯示我對一個郵箱的ACLs（即我在該郵箱上的許可權）。
- 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 設定
ANNOTATIONs。該方法非標準，但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的一個變體，對結果具有排序語義。返回的資料包含一個以空格分隔的匹配訊息編號列表。Sort 在 search_criterion 引數之前有兩個引數；一個帶括號的 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)¶
更改郵箱中訊息的標誌設定。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。大於三的值會跟蹤每個命令。
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()