IMAP 擴充功能

本文將說明 Gmail 提供的 IMAP 擴充功能，以及開發人員如何使用這些擴充功能。本文假設您熟悉 IMAP 通訊協定。

總覽

Gmail 提供一組 IMAP 擴充功能，讓 IMAP 用戶端作者透過 IMAP 提供更類似 Gmail 的體驗。如果開發人員要將 Gmail 功能整合至網頁或行動應用程式，建議改用符合 REST 樣式的 Gmail API。

您可以透過標準 IMAP 通訊協定或 OAuth 連線，使用這些擴充功能存取 Gmail。

檢查是否有擴充功能

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

回應會遵循「特殊用途」標準，並為 Gmail 的「重點」信箱新增 \Important 屬性 (即 "[Gmail]/Important")。

XLIST 已淘汰

我們在 2013 年淘汰了 Gmail 專用的 XLIST 指令，改用 IMAP 特殊用途清單標準。強烈建議客戶盡快從 XLIST 改用特殊用途業界標準。請注意，特殊用途標準屬性名稱與舊版 XLIST 屬性名稱相似，但並非完全相同。

SEARCH 指令的擴充功能：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，方便在多個資料夾中識別郵件。您可以透過 FETCH 指令的 X-GM-MSGID 屬性擷取這則訊息 ID。郵件 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)

X-GM-MSGID 屬性也可以用於 SEARCH 或 UID SEARCH 指令，根據 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)

X-GM-THRID 屬性也可以用於 SEARCH 或 UID SEARCH 指令，找出特定會話串中的訊息序號或 UID。以下是使用 UID SEARCH 指令擷取多則訊息的 UID 的呼叫內容示例：

a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)

存取 Gmail 標籤：X-GM-LABELS

Gmail 會將標籤視為 IMAP 的資料夾。因此，您可以使用標準 IMAP 指令 CREATE、RENAME 和 DELETE 來修改標籤，這些指令會對資料夾執行動作。系統標籤是指由 Gmail 建立的標籤，在標籤清單中會加上「[Gmail]」或「[GoogleMail]」前置字串。使用 XLIST 指令，即可取得信箱的完整標籤清單。

您可以使用 X-GM-LABELS 屬性搭配 FETCH 指令，擷取特定訊息的標籤。系統會以 ASTRING 清單的形式傳回該屬性，並視情況以 UTF-7 編碼。ASTRING 是 RFC 定義的原子或字串。

以下是呼叫的對話內容示例，該呼叫會使用 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)

X-GM-LABELS 屬性也可用於 SEARCH 或 UID SEARCH 指令，找出具有特定標籤的資料夾中所有郵件的序號或 UID。以下是使用 SEARCH 指令擷取多個訊息的序號的呼叫內容示例：

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

參考資料