IMAP 扩展

本文档介绍了 Gmail 提供的 IMAP 扩展功能，以及开发者如何使用这些功能。本文档假定您熟悉 IMAP 协议。

概览

Gmail 提供了一组 IMAP 扩展，以便 IMAP 客户端的作者通过 IMAP 提供更像 Gmail 的体验。将 Gmail 功能集成到其 Web 应用或移动应用中的开发者可能更愿意使用 RESTful 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 响应都包含这些特殊用途属性；这不是新的 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 已弃用

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 位无符号整数，也是 Web 界面和 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 位无符号整数，是 Web 界面和 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 命令获取邮箱的完整标签列表。

您可以使用 FETCH 命令搭配 X-GM-LABELS 属性来检索指定消息的标签。该属性以 ASTRING 列表的形式返回，并根据需要以 UTF-7 编码。ASTRING 是 RFC 中定义的 atom 或 string。

以下是使用 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)

参考