Method: users.history.list

列出指定邮箱的所有更改的历史记录。历史记录结果按时间顺序（historyId 递增）返回。

HTTP 请求

GET https://gmail.googleapis.com/gmail/v1/users/{userId}/history

网址采用 gRPC 转码语法。

路径参数

参数
userId

string

用户的电子邮件地址。特殊值 me 可用于表示经过身份验证的用户。

查询参数

参数
maxResults

integer (uint32 format)

要返回的历史记录数量上限。此字段的默认值为 100。此字段允许的最大值为 500。
pageToken

string

用于检索列表中特定结果页面的分页令牌。
startHistoryId

string

必需。返回指定 startHistoryId 之后历史记录。所提供的 startHistoryId 应从消息、会话或之前的 list 响应的 historyId 中获取。历史记录 ID 按时间顺序递增，但有效 ID 之间存在随机间隔，因此并不连续。提供无效或过期的 startHistoryId 通常会返回 HTTP 404 错误代码。historyId 通常至少在一周内有效，但在极少数情况下可能仅在几个小时内有效。如果您收到 HTTP 404 错误响应，您的应用应执行完全同步。如果您在响应中未收到任何 nextPageToken，则表示没有要检索的更新，您可以存储返回的 historyId 以用于将来的请求。
labelId

string

仅返回具有与 ID 匹配的标签的消息。
historyTypes[]

enum (HistoryType)

函数要返回的历史记录类型

请求正文

请求正文必须为空。

响应正文

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "history": [
    {
      object (History)
    }
  ],
  "nextPageToken": string,
  "historyId": string
}
字段
history[]

object (History)

历史记录列表。响应中包含的任何 messages 通常只会填充 id 和 threadId 字段。
nextPageToken

string

获取列表中下一页结果的网页令牌。
historyId

string

相应邮箱的当前历史记录的 ID。

授权范围

需要以下 OAuth 范围之一：

  • https://mail.google.com/
  • https://www.googleapis.com/auth/gmail.modify
  • https://www.googleapis.com/auth/gmail.readonly
  • https://www.googleapis.com/auth/gmail.metadata

如需了解详情，请参阅 OAuth 2.0 Overview。

HistoryType

枚举
messageAdded
messageDeleted
labelAdded
labelRemoved

历史记录

用户邮箱的更改记录。每次历史记录更改可能会以多种方式影响多条消息。

JSON 表示法 
{
  "id": string,
  "messages": [
    {
      object (Message)
    }
  ],
  "messagesAdded": [
    {
      object (MessageAdded)
    }
  ],
  "messagesDeleted": [
    {
      object (MessageDeleted)
    }
  ],
  "labelsAdded": [
    {
      object (LabelAdded)
    }
  ],
  "labelsRemoved": [
    {
      object (LabelRemoved)
    }
  ]
}
字段
id

string

邮箱序列 ID。
messages[]

object (Message)

相应历史记录中更改的消息的列表。特定更改类型的字段（例如 messagesAdded）可能会在此字段中重复显示消息。我们建议使用特定的更改类型字段，而不是此字段。
messagesAdded[]

object (MessageAdded)

此历史记录中添加到邮箱的消息。
messagesDeleted[]

object (MessageDeleted)

相应历史记录中从邮箱中删除（而非移至“已删除邮件”文件夹）的消息。
labelsAdded[]

object (LabelAdded)

此历史记录中添加到邮件的标签。
labelsRemoved[]

object (LabelRemoved)

相应历史记录中的邮件已移除的标签。

MessageAdded

JSON 表示法 
{
  "message": {
    object (Message)
  }
}
字段
message

object (Message)

MessageDeleted

JSON 表示法 
{
  "message": {
    object (Message)
  }
}
字段
message

object (Message)

LabelAdded

JSON 表示法 
{
  "message": {
    object (Message)
  },
  "labelIds": [
    string
  ]
}
字段
message

object (Message)
labelIds[]

string

添加到消息中的标签 ID。

LabelRemoved

JSON 表示法 
{
  "message": {
    object (Message)
  },
  "labelIds": [
    string
  ]
}
字段
message

object (Message)
labelIds[]

string

从邮件中移除的标签 ID。