Simulators
History feed
A sync client reads historyId from getProfile, polls history.list from it and keeps the historyId each page returns. Make two changes and read them back as records:
curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"gmail_busy_inbox"}' -o /dev/null
G=(-H 'Authorization: Bearer ya29.placeholder')
START=$(curl -s "$RYSTIC_URL/gmail/v1/users/me/profile" "${G[@]}" | jq -r .historyId)
curl -s "$RYSTIC_URL/gmail/v1/users/me/messages/19a4c0d1e2f31005/modify" "${G[@]}" -H 'Content-Type: application/json' -d '{"removeLabelIds":["UNREAD"]}' | jq -c '{id}'
# -> {"id":"19a4c0d1e2f31005"}
curl -s -X POST "$RYSTIC_URL/gmail/v1/users/me/messages/19a4c0d1e2f31005/trash" "${G[@]}" | jq -c '{id}'
# -> {"id":"19a4c0d1e2f31005"}
curl -s "$RYSTIC_URL/gmail/v1/users/me/history?startHistoryId=$START" "${G[@]}" | jq -c '[.history[] | keys - ["id", "messages"]]'
# -> [["labelsRemoved"],["labelsAdded","labelsRemoved"]]
curl -s "$RYSTIC_URL/gmail/v1/users/me/history?startHistoryId=$START&historyTypes=labelAdded" "${G[@]}" | jq -c '[.history[] | keys - ["id", "messages"]]'
# -> [["labelsAdded"]]
curl -s "$RYSTIC_URL/gmail/v1/users/me/history?startHistoryId=$START&maxResults=1" "${G[@]}" | jq -c '{records: (.history | length), more: (.nextPageToken != null)}'
# -> {"records":1,"more":true}
curl -s "$RYSTIC_URL/gmail/v1/users/me/history" "${G[@]}" | jq -c '.error | {code, status}'
# -> {"code":400,"status":"INVALID_ARGUMENT"}
curl -s "$RYSTIC_URL/gmail/v1/users/me/history?startHistoryId=999999999" "${G[@]}" | jq -c '.error | {code, status}'
# -> {"code":404,"status":"NOT_FOUND"}
The records each change lists
| Change | Record |
|---|---|
| inserting, importing or sending a message | messagesAdded |
| creating or updating a draft | messagesAdded |
| sending a draft | messagesDeleted, then messagesAdded |
| adding a label | labelsAdded |
| removing a label | labelsRemoved |
| trashing a message in the inbox | labelsAdded and labelsRemoved |
| deleting a message or a draft | messagesDeleted |
Each record carries its id, the messages it touched and the message’s labels after the change.
Filters and pages
historyTypes keeps only the kinds you name: messageAdded, messageDeleted, labelAdded or labelRemoved. labelId keeps only the changes to messages that carry that label. Pagination covers maxResults. A page with more carries nextPageToken, and the last one carries only the historyId to poll from next.
Errors
| Request | Returns |
|---|---|
no startHistoryId | 400 |
a startHistoryId past the mailbox’s current historyId | 404 notFound |
Differs from Gmail: history.list makes none of the refusals the other routes make. It returns the feed with no credential and reads any userId as me (Limitations).
No lag, no push
A change appears in the feed as soon as its write returns, as on Gmail. watch and stop publish to a Cloud Pub/Sub topic and are not served; poll history.list instead.