what_changed
Check what changed in a Gmail mailbox since a historyId: get message IDs for arrivals, removals, and label changes from Gmail's event log. Pass a previous historyId to see incremental updates without storing state.
Instructions
What happened in the mailbox since a point you already hold: messages that arrived or were removed, and labels applied or taken off — from Gmail's own event log, in one call. Pass the historyId a previous what_changed or get_profile returned; the reply carries the next one to keep. mailwarden stores NOTHING between calls, so the id lives with you. Reports EVENTS, not current state: a message that was marked unread and then read appears under both, and both are true. For how the mailbox looks NOW, use search or get_thread. Gmail keeps roughly a week of history. An id older than that is an ERROR, never an empty result — it means the question can no longer be answered incrementally, so take a fresh historyId from get_profile and re-establish state with search. labelId narrows the feed to events touching one label (e.g. 'INBOX', or a snooze label). Counts are complete even when the id lists are cut at 200 (truncated). USE WHEN: a recurring check — 'what came in since I last looked', watching a label, or confirming a bulk action landed. Far cheaper than re-running a search over the whole slice. DO NOT USE: for a first look at a mailbox (there is no id yet — start with triage_digest or search), or to read content: this returns ids only, no sender, subject or body. SIDE EFFECTS: none.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | ||
| labelId | No | ||
| sinceHistoryId | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| added | Yes | ||
| deleted | Yes | ||
| records | Yes | ||
| historyId | Yes | ||
| truncated | Yes | ||
| labelsAdded | Yes | ||
| labelsRemoved | Yes |