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 gmail account.

Once new message arrive I instantly get a push notification in valid format like:

{ message: 
    { data: '.......',
    attributes: {},
    message_id: '1248700053943' },
subscription: '.....' }

After I base64decode data I get email and historyId. Then, as suggested, I request gmail.users.history.list API (via API console) with startHistoryId set to the historyId from the push notification. And then get just empty response without any details:

GET https://www.googleapis.com/gmail/v1/users/me/history?startHistoryId=4658879&key={YOUR_API_KEY}
200 OK
- Show headers 
{
 "historyId": "4658894"
}

So historyId from a notification does not seems valid. Seems Gmail users.watch API is not working properly, and sends wrong historyId, or I'm just missing something?

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.