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 通常只填充 idthreadId 字段。

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。