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 從郵件中移除。