从 Email Settings API 迁移

本文介绍了 Email Settings API 与 Gmail API 之间的主要区别。您可以参考本指南将应用迁移到 Gmail API。

向请求授权

与 Email Settings API 一样，Gmail API 也使用 OAuth 2.0 协议向请求授权。一个主要区别是，Gmail API 权限的范围是限定为单个用户，而非整个网域。这意味着，授权网域管理员帐号将不允许您为网域中的其他用户迁移邮件。而必须使用管理控制台中已列入白名单的具有全网域授权的标准服务帐号，以生成相应的身份验证令牌。

Email Settings API 使用了以下范围：

https://apps-apis.google.com/a/feeds/emailsettings/2.0/

Gmail API 中的等效范围如下：

https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing

协议更改

Email Settings API 使用基于 XML 的 GDATA 协议。Gmail API 使用 JSON。由于设置主要由键值对组成，因此版本之间的载荷在概念上是相似的。

创建标签的示例：

Email Settings API

POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
  <apps:property name="label" value="status updates" />
</atom:entry>

Gmail API

POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
   "name": "status updates"
}

请使用提供的客户端库，而不是直接实现协议。

管理标签

如需在 Gmail API 中管理标签，请使用 Labels 资源。

旧设置 新设置 备注
labelId id
标签 name
unreadCount messagesUnread
visibility labelListVisibility SHOW 现已更名为 labelShow
HIDE 现已更名为 labelHide

其他变更：

  • 更新或删除标签时，Gmail API 会按 ID 而非名称来引用标签。

管理过滤器

要在 Gmail API 中管理过滤器，请使用过滤器资源。

旧设置 新设置 备注
来自 criteria.from
to criteria.to
对象 criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds 使用 INBOX 作为标签 ID
shouldMarkAsRead action.removeLabelIds 使用 UNREAD 作为标签 ID
shouldStar action.addLabelIds 使用 STARRED 作为标签 ID
标签 action.addLabelIds 使用要添加的标签 ID
forwardTo action.forward
shouldTrash action.addLabelIds 使用 TRASH 作为标签 ID
neverSpam action.removeLabelIds 使用 SPAM 作为标签 ID

其他变更：

  • 如果尚不存在添加用户标签，必须使用 labels.create 方法明确创建该标签。

管理“用以下地址发送邮件”别名

要在 Gmail API 中管理“发送身份”别名，请使用 SendAs 资源。

旧设置 新设置
name displayName
地址 sendAsEmail
replyTo replyToAddress
makeDefault isDefault

管理网页剪辑

不能再通过该 API 使用网页剪辑设置。

管理自动转发设置

如需在 Gmail API 中管理自动转发，请使用设置资源。

旧设置 新设置 备注
enable 已启用
forwardTo emailAddress
action disposition KEEP 现已更名为 leaveInInbox
ARCHIVE 现已更名为 archive
DELETE 现已更名为 trash
MARK_READ 现已更名为 markRead

其他变更：

  • 在使用前，必须先创建并验证转发地址
  • 转发地址可以通过 ForwardingAddresses 资源进行管理。

管理 POP 设置

如需在 Gmail API 中管理 POP 访问权限，请使用设置资源。

旧设置 新设置 备注
enable accessWindow 设为“disabled”时停用
enableFor accessWindow ALL_MAIL 现已更名为 allMail
MAIL_FROM_NOW_ON 现已更名为 fromNowOn
action disposition KEEP 现已更名为 leaveInInbox
ARCHIVE 现已更名为 archive
DELETE 现已更名为 trash
MARK_READ 现已更名为 markRead

管理 IMAP 设置

如需在 Gmail API 中管理 IMAP 访问权限，请使用设置资源。

旧设置 新设置
enable 已启用

管理休假自动回复设置

要在 Gmail API 中管理休假自动回复，请使用设置资源。

旧设置 新设置
contactsOnly restrictToContacts
domainOnly restrictToDomain
enable enableAutoReply
endDate endTime
信息 responseBodyHTML
responseBodyPlainText
startDate startTime
对象 responseSubject

管理签名设置

要在 Gmail API 中管理电子邮件签名，请使用 SendAs 资源。

旧设置 新设置
signature signature

其他变更：

  • 签名现在按别名进行管理。

管理语言设置

如需在 Gmail API 中管理语言设置，请使用设置资源。

旧设置 新设置
language displayLanguage

如需了解详情，请参阅管理语言设置指南。

管理委托设置

如需在 Gmail API 中管理委托，请使用 Delegates 资源。

旧设置 新设置
地址 delegateEmail
status verificationStatus

其他变更：

  • 常规
    • 如需使用任何委托方法（包括 delegates.create），必须为 Gmail 启用委托程序用户。例如，这意味着无法在Google Workspace中暂停委托人用户。
    • 电子邮件别名不能用作任何新方法的委托电子邮件地址输入。受托用户必须通过其主电子邮件地址获得推荐。
  • delegates.create
    • 此方法现在可用于在属于同一 Google Workspace组织的多个网域之间创建委托关系。
    • 现在，此方法可用于需要在下次登录时更改密码的用户。
    • 如果成功，此方法将在响应正文中返回 Users.settings.delegates 资源，而不是空的响应正文。
    • 如果委托人或受托用户已停用（例如，在 Google Workspace中挂起），则此方法会失败，并返回 HTTP 4XX 错误，而不是 HTTP 500 错误。
  • delegates.delete
    • 此方法现在可用于删除具有任何 verificationStatus 的委托，而不仅仅是 accepted 或 expired 的委托。
  • delegates.get
    • 这是一种新方法，可能需要比 delegates.list 方法更可取，具体取决于需要。

管理常规设置

无法再通过 API 使用常规设置。