本文件將介紹 Gmail 提供的 IMAP 擴充功能,以及開發人員可能如何使用這類擴充功能。本文假設您已熟悉 IMAP 通訊協定。
總覽
Gmail 提供一系列 IMAP 擴充功能,可讓 IMAP 用戶端的作者透過 IMAP 提供更類似 Gmail 的使用體驗。開發人員如要將 Gmail 功能整合至網頁或行動應用程式,可以改用符合 REST 樣式的 Gmail API。
透過標準 IMAP 通訊協定存取 Gmail 時,或透過 OAuth 連線時,系統都會使用擴充功能。
正在檢查擴充功能是否存在
Gmail 會在回應 CAPABILITY
指令時宣傳其擴充功能支援。本文件是否支援擴充功能,其支援功能清單中會指出 X-GM-EXT-1
。
強烈建議用戶端使用 IMAP ID 指令 (RFC 2971) 宣告,並附上聯絡人地址做為備用,以便在需要變更擴充功能時做為備用。
以下是在 Gmail IMAP 端點上握手及使用 CAPABILITY
指令的範例:
* OK Gimap ready for requests from 127.0.0.1 k2if6111336rvb.0
a001 LOGIN username@gmail.com password
a001 OK username@gmail.com authenticated (Success)
a001 OK Login successful
a002 CAPABILITY
* CAPABILITY IMAP4rev1 UNSELECT LITERAL+ IDLE NAMESPACE QUOTA ID XLIST CHILDREN X-GM-EXT-1
a002 OK Success
a003 ID ("name" "clientname" "version" "1.2.3" "vendor" "companyname" "contact" "foo@example.com")
* ID ("name" "GImap" "vendor" "Google, Inc." "support-url" "http://mail.google.com/support" "remote-host" "127.0.0.1")
a003 OK Success
LIST 指令的特殊使用擴充功能
Gmail 支援 IMAP 清單擴充功能適用於特殊資料夾,可為特殊資料夾提供新屬性。這些屬性可讓用戶端瞭解哪些資料夾屬於特殊資料夾 (例如\All
)。目前的特殊資料夾清單包括:已加星號、重要、寄件備份、草稿、垃圾郵件、所有郵件和垃圾桶。所有的 LIST
回應都含有這些特殊使用屬性,但這個 CAPABILITY
或用戶端需要 ENABLEd
的項目。
以下是對 LIST
的呼叫範例轉錄稿:
a004 LIST "" "*"
* LIST (\HasNoChildren) "/" "INBOX"
* LIST (\Noselect \HasChildren) "/" "[Gmail]"
* LIST (\HasNoChildren \All) "/" "[Gmail]/All Mail"
* LIST (\HasNoChildren \Drafts) "/" "[Gmail]/Drafts"
* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important"
* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail"
* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam"
* LIST (\HasNoChildren \Flagged) "/" "[Gmail]/Starred"
* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash"
a004 OK Success
回應符合特殊使用標準,並附上額外的 \Important
屬性供 Gmail 的優先收件匣 (例如 "[Gmail]/Important"
)。
淘汰 XLIST
Gmail 專用的 XLIST
指令已於 2013 年淘汰,並改用 IMAP 特殊使用清單標準。強烈建議客戶盡快從 XLIST
遷移至特殊使用業界標準。請注意,「特殊使用」標準屬性名稱與舊版 XLIST
屬性名稱相似,但並非完全相同。
搜尋指令的擴充功能:X-GM-RAW
為提供完整 Gmail 搜尋語法的存取權,Gmail 提供 X-GM-RAW
搜尋屬性。執行 SEARCH
或 UID SEARCH
指令時,與 X-GM-RAW
屬性一併傳遞的引數,與 Gmail 網頁介面中的解讀方式相同。
以下是使用 X-GM-RAW
屬性對 SEARCH
的呼叫範例文字記錄:
a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)
Gmail 專屬郵件 ID 存取權:X-GM-MSGID
Gmail 會為每封電子郵件提供專屬郵件 ID,讓使用者在多個資料夾中都能識別專屬郵件。支援擷取這個訊息 ID,方法是使用 FETCH
指令上的 X-GM-MSGID
屬性。郵件 ID 是 64 位元的無正負號整數,與網頁介面和 Gmail API 中使用的 ID 十六進位字串等於十進位。
以下是使用 FETCH
指令擷取訊息 X-GM-MSGID
的呼叫範例轉錄稿:
a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)
SEARCH
或 UID SEARCH
指令可能也會使用 X-GM-MSGID
屬性,根據 Gmail 的郵件 ID 找出郵件的序號或 UID
。以下是使用 UID SEARCH
指令擷取訊息 UID
的呼叫範例轉錄稿:
a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)
存取 Gmail 討論串 ID:X-GM-THRID
Gmail 會提供討論串 ID,讓您使用與 Gmail 網頁介面相同的方式,為多組郵件建立關聯。可透過 FETCH
指令上的 X-GM-THRID
屬性擷取這個執行緒 ID。執行緒 ID 為 64 位元的無正負號整數,與網頁介面和 Gmail API 中使用的 ID 十六進位字串等於十進位。
以下是使用 FETCH
指令擷取X-GM-THRID
數個訊息 (在兩個執行緒中) 的呼叫轉錄稿範例:
a008 FETCH 1:4 (X-GM-THRID)
* 1 FETCH (X-GM-THRID 1278455344230334865)
* 2 FETCH (X-GM-THRID 1266894439832287888)
* 3 FETCH (X-GM-THRID 1266894439832287888)
* 4 FETCH (X-GM-THRID 1266894439832287888)
a008 OK FETCH (Success)
您也可以在 SEARCH
或 UID SEARCH
指令中使用 X-GM-THRID
屬性,找出特定執行緒中訊息的序號或 UID
。以下是使用 UID SEARCH
指令擷取數則訊息 UID
的呼叫範例轉錄稿:
a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)
Gmail 標籤存取權:X-GM-LABELS
為執行 IMAP 存取,Gmail 會將標籤視為資料夾。因此,您可以使用對資料夾執行的標準 IMAP 指令 CREATE
、RENAME
和 DELETE
修改標籤。系統標籤是 Gmail 建立的標籤,會在標籤清單中保留並加上「[Gmail]」或「[GoogleMail]」前置字元。使用 XLIST
指令取得信箱的完整標籤清單。
您可以搭配 FETCH
指令使用 X-GM-LABELS
屬性,擷取特定郵件的標籤。這項屬性會以 ASTRING
清單的形式傳回,並視情況以 UTF-7 編碼。ASTRING
是 RFC 定義的「atom」atom或字串。
以下是使用 FETCH
指令擷取數則訊息 X-GM-LABELS
的呼叫範例轉錄稿:
a010 FETCH 1:4 (X-GM-LABELS)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante"))
* 2 FETCH (X-GM-LABELS (foo))
* 3 FETCH (X-GM-LABELS ())
* 4 FETCH (X-GM-LABELS (\Drafts))
a010 OK FETCH (Success)
可以使用 STORE
指令和 X-GM-LABELS
屬性在郵件中加入標籤。以下是轉錄稿範例,示範如何在訊息中加入標籤:
a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)
SEARCH
或 UID SEARCH
指令也可以使用 X-GM-LABELS
屬性,找出資料夾中所有已加上特定標籤的郵件的序號或 UID
。以下是呼叫範例,使用 SEARCH
指令擷取數則訊息的序號:
a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)
參考資料
- IMAP:RFC 3501:INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
- IMAP ID:RFC 2971: IMAP4 ID 延伸
- IMAP 特別用途:RFC 6154:特殊使用信箱的 IMAP LIST 擴充功能