IMAP 扩展

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

概览

Gmail 提供了一组 IMAP 扩展程序，以便 IMAP 客户端的作者通过 IMAP 提供更类似于 Gmail 的体验。 将 Gmail 功能集成到其 Web 应用或移动应用中的开发者可能希望改用 RESTful 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 LIST Extension for Special-Use Mailboxes，该扩展程序为特殊文件夹提供了新属性。这些属性让客户端知道哪些文件夹是特殊文件夹（例如 \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 的优先收件箱（即 "[Gmail]/Important"）添加了额外的 \Important 属性。

XLIST 已废弃

Gmail 特有的 XLIST 命令已于 2013 年废弃，取而代之的是 IMAP Special-Use List Standard。强烈建议客户端尽快从 XLIST 迁移到 Special-Use 行业标准。 请注意，Special-Use 标准属性名称与旧版 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 命令获取邮箱的完整标签列表。

您可以使用 FETCH 命令和 X-GM-LABELS 属性检索给定邮件的标签。该属性以 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)

参考