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 位的无符号整数，是网页界面和 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

在使用 IMAP 时，Gmail 会将标签视为文件夹。因此，您可以使用适用于文件夹的标准 IMAP 命令（CREATE、RENAME 和 DELETE）修改标签。系统标签是 Gmail 创建的标签，由系统预留，在标签列表中以“[Gmail]”或“[GoogleMail]”为前缀。使用 XLIST 命令可获取邮箱的完整标签列表。

可以结合使用 X-GM-LABELS 属性和 FETCH 命令来检索给定消息的标签。该属性会以 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)

X-GM-LABELS 属性也可在 SEARCH 或 UID SEARCH 命令中使用，用于查找文件夹中带有指定标签的所有邮件的序列号或 UID。以下是使用 SEARCH 命令检索多条消息的序列号的调用的转录示例：

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

参考