本文档介绍了如何使用 Gmail API 管理线程和邮件上的标签。
您可以使用标签在 Gmail 中标记、整理和分类邮件和会话。标签与邮件和会话之间存在多对多的关系：您可以为一封邮件或一个会话应用多个标签，也可以为多封邮件或多个会话应用一个标签。
如需了解如何创建、获取、列出、更新或删除标签，请参阅 labels 资源。
如需管理标签，您必须使用 https://www.googleapis.com/auth/gmail.labels 非敏感范围。如需详细了解范围，请参阅选择 Gmail API 范围。
标签类型
标签分为两种：预留 SYSTEM 标签和自定义 USER 标签。
系统标签通常对应于 Gmail 网页界面中的预定义元素，例如 INBOX。系统标签名称是预留名称；任何 USER 标签的名称都不能与任何 SYSTEM 标签的名称相同。下表列出了几种最常见的 Gmail 系统标签：
| 名称 | 可手动应用 | 备注 |
|---|---|---|
INBOX |
是 | |
SPAM |
是 | |
TRASH |
是 | |
UNREAD |
是 | |
STARRED |
是 | |
IMPORTANT |
是 | |
SENT |
否 | 自动应用于以下邮件：
|
DRAFT |
否 | 自动应用于通过 Gmail API 或 Gmail 界面创建的所有 draft 消息。 |
CATEGORY_PERSONAL |
是 | 对应于显示在 Gmail 界面“个人”标签页中的邮件。 |
CATEGORY_SOCIAL |
是 | 对应于 Gmail 界面“社交”标签页中显示的邮件。 |
CATEGORY_PROMOTIONS |
是 | 对应于 Gmail 界面“推广”标签页中显示的邮件。 |
CATEGORY_UPDATES |
是 | 对应于显示在 Gmail 界面“动态”标签页中的邮件。 |
CATEGORY_FORUMS |
是 | 对应于 Gmail 界面“论坛”标签页中显示的邮件。 |
管理对话和邮件中的标签
标签仅存在于消息中。如果您检索某个会话中的标签列表，则会获得该会话中任何邮件上存在的标签列表。一个消息串中的每条消息可能都没有标签。
您无法为草稿邮件应用标签。
在对话中添加或移除标签
在对话串中添加或移除标签时，系统会在该对话串中的所有现有邮件中添加或移除指定标签。
如果您在添加标签后向某个会话添加了消息，则新消息不会沿用与该会话关联的现有标签。如需向这些邮件添加标签，请再次向相应对话串添加标签。
如需添加或移除与某个会话相关联的标签，请使用 threads.modify。
为邮件添加或移除标签
为邮件添加标签后，该标签会添加到相应邮件，并与该邮件所属的对话串相关联。该标签不会添加到相应消息串中的其他消息。
如果您从某封邮件中移除某个标签，而该标签是相应会话中唯一包含该标签的邮件，那么该标签也会从相应会话中移除。
如需添加或移除应用于邮件的标签，请使用 messages.modify。