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。