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)

參考資料