选择 Gmail API 范围

本文档包含 Gmail API 专属的授权和身份验证信息。在阅读本文档之前,请务必参阅 了解身份验证和授权,了解 Google Workspace 的一般身份验证和授权信息。

配置 OAuth 2.0 以进行授权

配置 OAuth 权限请求页面并选择范围,以定义向用户和应用审核者显示哪些信息,并注册应用以便以后发布。

Gmail API 权限范围

如需定义授予应用的访问权限级别,您需要确定并声明授权范围。授权范围是 OAuth 2.0 URI 字符串,其中包含 Google Workspace 应用名称、它访问的数据类型以及访问权限级别。范围是您的应用请求处理 Google Workspace 数据(包括用户的 Google 账号数据)的请求。

在用户安装您的应用时,系统会要求用户验证该应用使用的范围。通常,您应尽可能选择最窄的范围,并避免请求应用不需要的范围。用户更乐意向描述清晰的有限范围授予访问权限。

Gmail API 支持以下范围:

范围代码 说明 用法
https://www.googleapis.com/auth/gmail.addons.current.action.compose 当您与该插件互动时管理草稿和发送电子邮件。 非敏感
https://www.googleapis.com/auth/gmail.addons.current.message.action 在您与该插件互动时查看您的电子邮件。 非敏感
https://www.googleapis.com/auth/gmail.addons.current.message.metadata 在该插件运行时查看您的电子邮件元数据。 敏感内容
https://www.googleapis.com/auth/gmail.addons.current.message.readonly 在该插件运行时查看您的电子邮件。 敏感内容
https://www.googleapis.com/auth/gmail.labels 仅限创建、读取、更新和删除标签。 非敏感
https://www.googleapis.com/auth/gmail.send 仅发送消息。无权读取或修改邮箱。 敏感内容
https://www.googleapis.com/auth/gmail.readonly 读取所有资源及其元数据,但无法执行写入操作。 受限
https://www.googleapis.com/auth/gmail.compose 创建、读取、更新和删除草稿。发送消息和草稿。 受限
https://www.googleapis.com/auth/gmail.insert 仅插入和导入消息。 受限
https://www.googleapis.com/auth/gmail.modify 所有读写操作,但绕过回收站立即永久删除会话和邮件除外。 受限
https://www.googleapis.com/auth/gmail.metadata 读取资源元数据,包括标签、历史记录和电子邮件正文标头,但不包括正文或附件。 受限
https://www.googleapis.com/auth/gmail.settings.basic 管理基本邮件设置。 受限
https://www.googleapis.com/auth/gmail.settings.sharing 管理敏感邮件设置,包括转发规则和别名。

注意:受此作用域保护的操作仅限于管理用途。只有使用具有全网域委派权限的服务账号的 Google Workspace 客户才能使用这些功能。
受限
https://mail.google.com/ 对账号邮箱的完全访问权限,包括永久删除会话和邮件。仅当您的应用需要绕过回收站立即永久删除会话和邮件时,才应请求此范围;所有其他操作都可以使用权限较低的范围执行。 受限

上表中的“使用情况”列表示每个镜的敏感度,具体定义如下:

  • 非敏感:这些范围提供最小范围的授权访问权限,并且只需进行基本应用验证。如需了解此要求,请参阅准备验证的步骤

  • 敏感 - 这些范围允许访问 Google 用户数据,并且需要完成敏感范围验证流程。如需了解此要求,请参阅 Google API 服务:用户数据政策。这些范围不需要进行安全评估。

  • 受限 - 这些范围可提供对 Google 用户数据的广泛访问权限,并且需要您完成受限范围验证流程。如需了解此要求,请参阅 Google API 服务:用户数据政策针对特定 API 范围的其他要求。如果您在服务器上存储(或传输)受限范围的数据,则需要接受安全评估。

如需了解在您请求访问用户数据时,关于您使用和访问 Gmail API 的其他信息,请参阅 Gmail API 服务用户数据和开发者政策

如果您的应用需要访问任何其他 Google API,您也可以添加这些范围。如需详细了解 Google API 范围,请参阅使用 OAuth 2.0 访问 Google API

OAuth 验证

使用某些敏感 OAuth 范围可能需要您的应用完成 Google 的 OAuth 验证流程。请参阅 OAuth 验证常见问题解答,确定您的应用何时应进行验证以及需要进行哪种类型的验证。另请参阅 Google API 服务:用户数据政策