IMAP 扩展

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

概览

Gmail 提供了一组 IMAP 扩展，以便 IMAP 客户端的作者通过 IMAP 提供更类似 Gmail 的体验。将 Gmail 功能集成到其 Web 或移动应用中的开发者可能更希望使用 RESTful Gmail API。

在通过标准 IMAP 协议访问 Gmail 或通过 OAuth 连接时，可能会使用这些扩展程序。

检查是否存在扩展程序

Gmail 会在响应 CAPABILITY 命令时宣传其扩展程序支持。本文档中扩展程序的支持情况通过支持的 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 的优先收件箱（即 "[Gmail]/Important"）添加了额外的 \Important 属性。

XLIST 已废弃

我们于 2013 年弃用了 Gmail 专用 XLIST 命令，改用 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)

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

Gmail 会将标签视为文件夹，以便使用 IMAP。因此，您可以使用对文件夹执行操作的标准 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)

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

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

参考