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

如需了解详情，请参阅授权指南。

历史记录类型

枚举
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)

已从此历史记录中的邮件移除标签。

添加了消息

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

object (Message)

消息已删除

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

object (Message)

添加了标签

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

object (Message)
labelIds[]

string

为邮件添加了标签 ID。

已移除标签

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

object (Message)
labelIds[]

string

已从邮件中移除标签 ID。