IMAP 擴充功能

本文件將介紹 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 搜尋屬性。執行 SEARCHUID 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)

SEARCHUID 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)

您也可以在 SEARCHUID 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 指令 CREATERENAMEDELETE 修改標籤。系統標籤是 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)

SEARCHUID SEARCH 指令也可以使用 X-GM-LABELS 屬性,找出資料夾中所有已加上特定標籤的郵件的序號或 UID。以下是呼叫範例,使用 SEARCH 指令擷取數則訊息的序號:

a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)

參考資料