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?

Are you sure you are using the exact same email address in your test application as in the API Explorer? — Tholle
@Tholle, Yes. Also, if I subtract a bit from provided historyId, say, not 4658879 but 4658800 and use it as startHistoryId I'm able to grab data about new message somewhere in the middle of response array. It's not accurate, and works like a magic, I need straightforward way to get exact data by a histroyId from a push message. — Yaroslav Pogrebnyak

Yaroslav Pogrebnyak Yaroslav Pogrebnyak · Accepted Answer · 2015-08-04T19:51:32

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

Remember historyId from the response of users.watch request.
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.
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.

Gmail API users.watch - no details for historyId

1 Answers