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。