Gmail API「Users.messages:list」と「Users.history:list」の違い

@koshi_life です。

Gmail APIを使って、一定期間の過去メールを取得する機会があり、
最初、messages:list API とhistory:list API の違いがわからなかったので、調べた内容を備忘します。

TL;DR / 比較表

API	messages:list	history:list
公式Doc説明	>Lists the messages in the user's mailbox.	>Lists the history of all changes to the given mailbox. History results are returned in chronological order (increasing historyId).
意訳および使い方	メールボックスに対し検索した結果をメールID/スレッドID一覧を返却するAPI。 検索はqパラムにGmail QueryFormatのフォーマットで指定可能。	メールボックスに対する状態ID historyId を指定し、それ以降の変更されたイベントを取得するAPI。 イベント種別historyTypesは４種labelAdded,labelRemoved,messageAdded,messageDeleted。
備考		ユーザの現在の historyId は getProfile API で把握可能。参考 変更情報を取得するPush Notifications で受け取れるのはこのhistoryIdが連携されます。参考

サンプルレスポンス

Google API Documentの右側の「Try this API」で
試したサンプルレスポンスを参考までに貼っておきます。

messages:list

messages-list.json

{
 "messages": [
  {
   "id": "xxx1",
   "threadId": "xxx1"
  },
  {
   "id": "xxx2",
   "threadId": "xxx2"
  }
 ],
 "nextPageToken": "xxx",
 "resultSizeEstimate": 11
}

history:list

history-list.json

{ "history": [
  {
   "id": "xxx455",
   "messages": [
    {
     "id": "xxx1",
     "threadId": "xxx1"
    }
   ],
   "messagesAdded": [
    {
     "message": {
      "id": "xxx1",
      "threadId": "xxx1",
      "labelIds": [
       "UNREAD",
       "CATEGORY_UPDATES",
       "INBOX"
      ]
     }
    }
   ]
  },
  {
   "id": "xxx600",
   "messages": [
    {
     "id": "xxx2",
     "threadId": "xxx2"
    }
   ],
   "messagesAdded": [
    {
     "message": {
      "id": "xxx2",
      "threadId": "xxx2",
      "labelIds": [
       "UNREAD",
       "IMPORTANT",
       "CATEGORY_UPDATES",
       "INBOX"
      ]
     }
    }
   ]
  }
 ],
 "nextPageToken": "xxx",
 "historyId": "xxx"
}

簡単ですが以上です。