Gmail API users.watch - no details for historyId

Question

I have successfully set up Google Pub/Sub to use Gmail API Watch feature as described here: https://developers.google.com/gmail/api/guides/push to watch INBOX label in my gm

Answer 1

Looks like I misunderstood how users.history.list works, and the flow should be something like described below:

1. Remember historyId from the response of users.watch request.

2. On push notification call users.history.list with previously remembered historyId as startHistoryId instead of new one from notification, and get list of recent changes.

3. Remember historyId from notification, and goto 2.

If we look on the response of any call to users.history.list, historyId is always present, it's a marker of latest history change. Push notification brings latest historyId, so if we request users.history.list with it (as in the question), we got empty array of history, and the server drops this empty "history" field from the response, that's why we get this:

{
 "historyId": "4658894"
}

But not this:

{
 "history": [ ],
 "historyId": "4658894"
}

More details provided in sync guide: https://developers.google.com/gmail/api/guides/sync#partial

So we can't easily get details of the new message arrived to INBOX from push notification, and need to deal with history mining and synchronization to find it.