从 Email Settings API 迁移

本文档可帮助您将应用从已废弃的 Email Settings API 迁移到 Gmail API。

向请求授权

与 Email Settings API 一样，Gmail API 使用 OAuth 2.0 协议向请求授权。一个主要区别在于，Gmail API 权限的作用范围是单个用户，而不是整个网域。 这意味着，授权网域管理员账号并不能让您为网域中的其他用户迁移邮件。相反，您必须使用 标准服务 账号，这些账号具有网域级权限 ，并且已添加到 Google 管理控制台中的许可名单，以便生成适当的 身份验证令牌。

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
label name
unreadCount messagesUnread
visibility labelListVisibility SHOW 现在是 labelShow
现在是 HIDElabelHide

其他变更：

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

管理过滤条件

如需在 Gmail API 中管理过滤条件，请使用 settings.filters 资源。

旧设置 新设置 备注
from criteria.from
to criteria.to
subject 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
label action.addLabelIds 使用要添加的标签的 ID
forwardTo action.forward
shouldTrash action.addLabelIds 使用 TRASH 作为标签 ID
neverSpam action.removeLabelIds 使用 SPAM 作为标签 ID

其他变更：

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

管理“以…身份发送”别名

如需在 Gmail API 中管理“以…身份发送”别名，请使用 settings.sendAs资源。

旧设置 新设置
name displayName
address sendAsEmail
replyTo replyToAddress
makeDefault isDefault

管理网络剪辑

Gmail API 中没有网络剪辑设置。

管理自动转发

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

旧设置 新设置 备注
enable enabled
forwardTo emailAddress
action disposition KEEP 现在是 leaveInInbox
ARCHIVE 现在是 archive
DELETE 现在是 trash
MARK_READ 现在是 markRead

其他变更：

管理 POP 设置

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

旧设置 新设置 备注
enable accessWindow 设置为 disabled 时停用
enableFor accessWindow ALL_MAIL 现在是 allMail
现在是 MAIL_FROM_NOW_ONfromNowOn
action disposition KEEP 现在是 leaveInInbox
ARCHIVE 现在是 archive
DELETE 现在是 trash
MARK_READ 现在是 markRead

管理 IMAP 设置

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

旧设置 新设置
enable enabled

管理外出自动回复设置

如需在 Gmail API 中管理外出自动回复，请使用 settings 资源。

旧设置 新设置
contactsOnly restrictToContacts
domainOnly restrictToDomain
enable enableAutoReply
endDate endTime
message responseBodyHtml
responseBodyPlainText
startDate startTime
subject responseSubject

管理签名设置

如需在 Gmail API 中管理电子邮件签名，请使用 settings.sendAs 资源。

旧设置 新设置
signature signature

其他变更：

  • 现在按别名管理签名。

管理语言设置

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

旧设置 新设置
language displayLanguage

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

管理委托设置

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

旧设置 新设置
address delegateEmail
status verificationStatus

其他变更：

  • 概要
    • 如需使用任何委托方法（包括 settings.delegates.create），必须为委托人用户启用 Gmail。也就是说，例如，不能在 Google Workspace 中暂停委托人用户。
    • 对于任何新方法，邮箱别名都不能用作受托人电子邮件输入。必须使用委托用户的电子邮件地址来引用委托用户。
  • settings.delegates.create
    • 此方法现在可用于在属于同一 Google Workspace 组织的多个网域中创建委托关系。
    • 此方法现在可用于需要在下次登录时更改密码的用户。
    • 如果成功，此方法会在响应正文中返回 settings.delegates 资源，而不是返回空响应正文。
    • 如果委托人用户或委托用户被停用（例如，在 Google Workspace 中被暂停），此方法会失败并显示 HTTP 4XX 错误，而不是 HTTP 500 错误。
  • settings.delegates.delete
    • 此方法现在可用于删除具有任何 VerificationStatus的委托，而不仅仅是 accepted 或 expired 的委托。
  • settings.delegates.get

管理常规设置

Gmail API 中没有常规设置。