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，也不是客户端必须启用的功能。

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

您还可以使用 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 位无符号整数，是 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)

您还可以使用 SEARCH 或 UID SEARCH 命令中的 X-GM-THRID 属性来查找给定线程中消息的序列号或 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]”前缀，并且是预留的。使用 LIST 命令获取邮箱的完整标签列表。

您可以使用 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)

您还可以使用 SEARCH 或 UID SEARCH 命令中的 X-GM-LABELS 属性来查找具有指定标签的文件夹中所有消息的序列号或 UID。以下是使用 SEARCH 命令检索多条消息的序列号的调用示例记录：

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

参考