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

有关详情，请参阅授权指南。

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。