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。