本文介绍了 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
的委托。
- 此方法现在可用于删除具有任何 verificationStatus 的委托,而不仅仅是
- delegates.get
- 这是一种新方法,可能需要比 delegates.list 方法更可取,具体取决于需要。
管理常规设置
无法再通过 API 使用常规设置。