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 LIST 擴充功能，可為特殊資料夾提供新屬性。這些屬性可讓用戶端瞭解哪些資料夾是特殊資料夾 (例如 \All)。目前特殊資料夾清單包含：已加星號、重要、寄件備份、草稿、垃圾郵件、所有郵件和垃圾桶。所有 LIST 回覆都包含這些特殊用途屬性；這並非新功能，客戶也無需採取任何行動。CAPABILITYENABLEd

以下是呼叫 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 已淘汰

Gmail 專用的 XLIST 指令已於 2013 年淘汰，改用 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)

您也可以在 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)

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

就 IMAP 而言，Gmail 會將標籤視為資料夾。因此，您可以使用標準 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)

參考資料