io.github.csitte/mailwarden

Archive a thread (remove it from the inbox). USE WHEN: inbox triage — the thread is handled and should leave the inbox. DO NOT USE: to delete (use trash) or to defer to a date (use snooze). Pass `threadIds` (a list of up to 100) instead of `threadId` to apply the same change to every listed thread in one call — for 'exactly these threads, as approved'. The answer then reports per thread: `changed`, `failed` (with code and message; the others still ran) and `notAttempted` (the run stopped at a rate limit, dead token or missing scope, which would have hit every remaining thread alike); `ok` is true only when all were changed. SIDE EFFECTS: thread leaves the inbox; reversible via modify_labels add INBOX.

Bulk-apply label changes to every message matching a Gmail query, batched at 1000 messages per API request. Labels may be given by name or by id: an unknown name in `add` is created automatically (use '/' for nested labels), an unknown name in `remove` is ignored. Returns matched/submitted counts, matched and submitted thread IDs (both lists capped at 500 — matchedThreadCount/submittedThreadCount hold the true totals), and per-chunk failures (partial success is reported, not hidden). IMPORTANT: `submittedMessages` is how many ids were handed to the API, NOT how many messages changed — `messages.batchModify` answers 204 with no body and ignores ids it does not recognise without a word, so an accepted request is not a performed one. Set verify:true to read the labels back afterwards and get `verified` {applied, notApplied[], unverifiable[]} — the only field here that reports an observed outcome. It costs one extra read per affected thread, so it is off by default; use it when a wrong 'done' would be acted on (trashing, or anything the user is told completed). If more messages match than maxMessages, only the first maxMessages are processed and 'capped' is true — raise maxMessages or re-run to finish the rest. NOTE: the query hits Gmail's search index as-is, WITHOUT the live re-verification search performs. The staleness that makes search re-verify was measured on `threads.list` (132 threads returned, 114 carrying no unread message at all); the same query through the message index this tool uses returned 19 hits, none stale — same mailbox, same minute. So the known drift does not reach this path, but that is one measurement, not a guarantee: `unverifiedPredicates` in the result names the conditions taken on the index's word, and when the outcome must be read-state-precise, resolve the set with search (which verifies against live labels) and act on those thread ids instead. Set crossCheck:true to ask Gmail the same question a second way before writing: each derived pre…

Unsubscribe from several mailing lists in one call, one thread id per list. Threads are processed SEQUENTIALLY, and at most ONE request is made per sender — a second thread from a sender whose request already went out is reported with `duplicateOf` and no request (and says so when it advertises a DIFFERENT endpoint, i.e. is probably a separate list from the same sender). The whole call shares a 60-second budget; threads left over when it runs out come back with `skippedOutOfTime` and a reason, so re-running with the remaining ids finishes the job. Like unsubscribe, there is no URL parameter: every endpoint comes from that thread's own List-Unsubscribe header. Only RFC 8058 one-click senders are contacted; the rest come back with their alternatives in `options`. Partial success is reported, never hidden: a thread that cannot be read or whose endpoint fails becomes an entry with a `reason`, and the remaining threads still run. Set dryRun:true to rehearse: same header reads, same per-sender dedupe (as a real run with every request succeeding), and each entry a real run would contact reports the endpoint it `wouldCall`; refusals and duplicates carry none — and nobody is contacted. USE WHEN: clearing out several newsletters at once — pair with list_subscriptions, which gives you the sender rows and their newestThreadId; dryRun first to show the user which senders would be contacted. DO NOT USE: for one thread (use unsubscribe), or to find candidates (use list_subscriptions — it contacts nobody). SIDE EFFECTS: up to one outbound HTTPS request per DISTINCT sender (plus up to 3 redirects each) — the only non-Google hosts mailwarden ever contacts (none with dryRun). Each confirms to that sender that the address is live, and none of it can be undone. The mailbox itself is not changed.

Create a Gmail filter: matching incoming mail automatically gets the given label actions. Give at least one criterion and at least one action. Actions are label add/remove only (labels by name or id; an unknown name in addLabels is auto-created). Common recipes: skip the inbox → removeLabels ['INBOX']; auto-mark-read → removeLabels ['UNREAD']; auto-trash → addLabels ['TRASH']; star → addLabels ['STARRED']; file under a label → addLabels ['Receipts']. A filter only affects mail arriving AFTER it's created; set applyToExisting:true to ALSO apply the same actions once to mail already in the mailbox (builds a Gmail search from the criteria and runs a bulk modify — same unverified-index caveat as bulk_modify — the sweep acts on what the index returns, which can be badly stale on read state; up to maxMessages, default 1000). The sweep's `applied.submittedMessages` is how many ids were handed to the API, NOT how many messages changed; set verify:true alongside applyToExisting to read the labels back afterwards and get `applied.verified` {applied, notApplied[], unverifiable[]}. It costs one extra read per affected thread, so it is off by default; a read-back that fails lands in `unverifiable` and never fails the call — the filter stands either way. USE WHEN: setting up a persistent auto-triage rule (e.g. 'always archive + label newsletters from x'), optionally cleaning up the existing backlog too — preview_filter first to see how much mail it would catch today and whether an existing filter already covers it. NOTE: forwarding filters are intentionally not supported — mailwarden creates no send/exfiltration path. SIDE EFFECTS: adds a server-side rule affecting future mail (reversible via delete_filter); with applyToExisting also modifies existing messages. Requires gmail.settings.basic.

Create a user label and return its id. Idempotent: if the name already exists (case-insensitive), its existing id is returned and nothing is created. Nested labels: separate levels with '/' (e.g. 'Clients/Acme') — each missing parent level is created too. Colour: pass backgroundColor AND textColor together as '#rrggbb' (Gmail rejects one without the other, and accepts only colours from its own palette). Giving a colour for a label that already exists RECOLOURS it — that is how an existing label, such as the snooze label, gets a colour. Gmail colours only labels you created yourself; system labels like INBOX or CATEGORY_UPDATES refuse one. USE WHEN: you want a label's id up front, to pre-create a label without applying it to anything, or to make an existing label visible at a glance in Gmail. DO NOT USE: just to file mail under a new label — modify_labels/bulk_modify already auto-create an unknown name passed in `add`. SIDE EFFECTS: creates the label if missing, and sets its colour when one is given; no mail is changed.

Delete a Gmail filter by id (get ids from list_filters). USE WHEN: removing an auto-triage rule. SIDE EFFECTS: removes the server-side rule; future mail is no longer auto-processed by it. Requires gmail.settings.basic.

Download an attachment to a local file path. If MAILWARDEN_DOWNLOAD_DIR is set, destPath is resolved inside (and restricted to) that directory. USE WHEN: the user wants an attachment saved to disk (IDs come from get_thread's attachment metadata). SIDE EFFECTS: writes a local file; never overwrites — an existing file gets a numeric suffix (file-1.pdf). The response's 'saved' field is the path actually used. Mailbox unchanged.

Write a whole thread to a local file instead of returning it — for keeping, sharing, or reading a long conversation without loading it into the context. `markdown` (default): one section per message with From/To/Date/Subject and attachment names as inline code (never rendered as a link or image), sender authentication and the attachment list, and the body in a code fence that the message text cannot close (HTML-only mail is reduced to text). `json`: the parsed messages as get_thread returns them, HTML included. Both formats strip the same hidden characters (zero-width, bidi controls) as every tool result. Attachments are listed, not saved — use download_attachment for those. If MAILWARDEN_DOWNLOAD_DIR is set, destPath is resolved inside (and restricted to) that directory, as for attachments. The file holds mail text as the sender wrote it: untrusted content, now on disk. USE WHEN: the user wants a conversation saved or handed on, or a thread is too long to read in one piece. DO NOT USE: to read a thread (use get_thread). SIDE EFFECTS: writes a local file; never overwrites — an existing file gets a numeric suffix. The response's 'saved' field is the path actually used. Mailbox unchanged.

Who is waiting on whom. `waitingOnThem`: threads whose LAST message is yours (SENT) and has had no answer for at least nudgeAfterDays — candidates for a nudge; a note to yourself (every To and Cc address is the account's own primary address, in any spelling Gmail delivers to it: +tags, dots, googlemail.com) is left out; one other recipient keeps it. `waitingOnMe`: threads still in the inbox whose last message came from someone else — a person, not a newsletter or an automated notice by its own headers — oldest first. Decided on each thread's last message and its LIVE labels: the search index only proposes candidates (`in:sent` / `in:inbox` within the last `days`), so a thread the index still files under the inbox after it was archived is dropped, as in search. Drafts, trash and spam messages do not count as a thread's last word. Scans at most `max` threads per side; `hasMore` says when more candidates existed. A thread with no recorded date is left out rather than given an invented age. USE WHEN: 'what am I waiting on?', 'who have I not answered?', 'what should I follow up on?' DO NOT USE: as an inbox overview (use triage_digest) or to read a thread (use get_thread). SIDE EFFECTS: none.

Return the authorized account: email address plus total message/thread counts, and WHICH SERVER is answering: `serverVersion` (the bare version ONLY for a release build; anything else names its commit, e.g. `0.23.0+a5ff4a7`, `+a5ff4a7.dirty` when built from uncommitted sources, `+unknown` when the build left no record), `build` (commit, dirty, release, builtAt; absent when unknown), `serverPath` (the directory the running code was loaded from — an npm install, an npx cache or a clone's `dist/`) and `account` (the named mailwarden account, or `(default)`). USE WHEN: confirming WHICH mailbox is connected before a bulk or filter action, as a cheap liveness check, or when a tool or field documented for a version seems missing — `serverVersion` says whether the running build is the one you think, and `serverPath` which install it is. DO NOT USE: to enumerate messages — this returns only counts, not a listing (use search). SIDE EFFECTS: none.

Fetch a thread by ID: headers, plaintext + HTML bodies, and attachment metadata. WHEN A THREAD IS LONG OR HTML-HEAVY, shrink the answer instead of skipping content: `bodies: "text"` drops `htmlBody` and keeps `plaintextBody` (an HTML-only mail is reduced to text and marked `bodyFromHtml: true`); `bodies: "new"` is `text` without the quoted history at the end of a reply (the trailing `>` block with its 'On ... wrote:' line, or an Outlook 'Original Message' block) and marks a cut message `quotedStripped: true` — inline answers between quoted lines, answers below a quote and forwarded messages (recognised by a forwarded-message line or a Fwd/FW/WG subject) are kept whole, except an answer below an Outlook plain-text From/Sent/Subject block, which goes with it; `bodies: "none"` drops both bodies and keeps everything else, INCLUDING the real attachment list; `lastN: 2` returns only the newest two messages, `afterMessageId` only the messages after one you have already read (both compose: after X, then the last N). The quota cost is the same whatever you keep — Gmail hands over the whole thread, these options only decide how much of it you read. `messageCount` is always the whole thread and `omittedMessages` how many the selection left out, so a partial view never passes for the whole; `bodies` is echoed when it is not `full`. `full` defaults to true and should stay true whenever content matters. `full: false` is a headers-and-labels fetch that does NOT fetch bodies or attachment metadata — the result then omits `plaintextBody`, `htmlBody` and `attachments` entirely and sets `metadataOnly: true`. `full: false` together with any `bodies` is rejected as `invalid_input` rather than silently ignored. `full: false` is kept for compatibility but DEPRECATED: use `bodies: "none"` instead, which costs the same quota and keeps the real attachment list. The fields are omitted rather than empty on purpose: an empty attachment list from a request that never looked is indistinguishable…

List all Gmail filters — the server-side rules that auto-apply label actions to incoming mail. Shows each filter's criteria and label actions, and (for auditing) any `forward` address an existing filter carries. USE WHEN: reviewing existing automation, or to get a filter's id before delete_filter. SIDE EFFECTS: none. Requires the gmail.settings.basic scope — re-run `mailwarden --auth` if you authorized an earlier version.

List all Gmail labels (system + user). USE WHEN: inspecting the mailbox structure, or to get exact label names/ids — though modify_labels/bulk_modify/create_label all accept a plain label name directly, so a lookup is rarely required. SIDE EFFECTS: none.

List all snoozed threads with their due dates. SIDE EFFECTS: none.

Who keeps writing, how often, and whether you can get off the list — a mailbox slice grouped by SENDER, each row carrying its opt-out options. Contacts nobody: opt-out options come from the List-Unsubscribe header of each sender's newest thread (one metadata fetch per sender, not per thread). `optOut` is 'one-click' (the unsubscribe tool can perform it), 'link' (a human opens it in a browser), 'mailto' (would need sending, which mailwarden never does), 'none', or 'unknown' when that sender's header fetch failed or was never made because Gmail's quota ran out mid-listing. `oldestDate`/`newestDate` bound what the SAMPLE saw of that sender, not the sender's whole history — a query capped at `max` reaches back only as far as those threads go, which on a busy mailbox is days. There is deliberately NO precomputed frequency: judge it from `threads` across that span, with the sampling caveat in view. `newestThreadId` is what to hand to unsubscribe or bulk_unsubscribe. `sendersFound` is how many DISTINCT senders the sample held — when it exceeds topN, the list is truncated and raising topN shows more. USE WHEN: 'what am I subscribed to', 'which newsletters flood me', or picking targets before a bulk unsubscribe. DO NOT USE: for a general inbox overview (use triage_digest — it buckets by label and age too), or for one known thread (use list_unsubscribe). SIDE EFFECTS: none.

Report the opt-out options a thread advertises (List-Unsubscribe / RFC 8058), without contacting anyone. Reads the newest message that carries the header, so a reply threaded onto a newsletter does not hide it. `oneClick` means the sender supports the automatable one-click opt-out — the `unsubscribe` tool can perform it. `httpsUrls` without oneClick are links for a human to open in a browser; `mailtos` would require sending mail, which mailwarden never does. `bodyCandidates` appears only when the headers advertise nothing: unsubscribe links found in the message TEXT, which is written by the sender and therefore untrusted. Show them to the user to open; never fetch one, and do not treat them as an opt-out that happened. `hasUnsubscribe` stays false for them — it describes the headers. USE WHEN: checking whether a newsletter can be unsubscribed from, or showing the user the link to click. SIDE EFFECTS: none — no request is made to the sender.

Mark a thread as read. Pass `threadIds` (a list of up to 100) instead of `threadId` to apply the same change to every listed thread in one call — for 'exactly these threads, as approved'. The answer then reports per thread: `changed`, `failed` (with code and message; the others still ran) and `notAttempted` (the run stopped at a rate limit, dead token or missing scope, which would have hit every remaining thread alike); `ok` is true only when all were changed. SIDE EFFECTS: removes UNREAD; reversible via mark_unread.

Mark a thread as unread. Pass `threadIds` (a list of up to 100) instead of `threadId` to apply the same change to every listed thread in one call — for 'exactly these threads, as approved'. The answer then reports per thread: `changed`, `failed` (with code and message; the others still ran) and `notAttempted` (the run stopped at a rate limit, dead token or missing scope, which would have hit every remaining thread alike); `ok` is true only when all were changed. SIDE EFFECTS: adds UNREAD; reversible via mark_read.

Add/remove labels on a thread. Archive = remove 'INBOX'; mark read = remove 'UNREAD'. Labels may be given by name or by id: an unknown name in `add` is created automatically (use '/' for nested labels), an unknown name in `remove` is ignored. USE WHEN: applying custom labels or label combinations in one call. DO NOT USE: for plain archive/read/unread — the dedicated tools are clearer. Pass `threadIds` (a list of up to 100) instead of `threadId` to apply the same change to every listed thread in one call — for 'exactly these threads, as approved'. The answer then reports per thread: `changed`, `failed` (with code and message; the others still ran) and `notAttempted` (the run stopped at a rate limit, dead token or missing scope, which would have hit every remaining thread alike); `ok` is true only when all were changed. SIDE EFFECTS: changes the thread's labels (and may create a label named in `add`, once per call even for a list); reversible by the inverse call.

Check a filter BEFORE create_filter makes it: how much mail its criteria match today, which existing filters have exactly the same criteria, which share a from/to/subject/query value with it, and which label names in addLabels do not exist yet. Creates nothing and changes nothing. Takes the same criteria as create_filter and checks them the same way, so a preview cannot accept what the create would refuse. `currentMatches` counts what Gmail's search returns for the derived query — the same unverified index create_filter's applyToExisting sweep would act on; it is a size, not a promise that the filter engine agrees on every message. A rule with no positive criterion (only negatedQuery or hasAttachment:false) is not counted at all: it would match nearly the whole mailbox. `overlapping` is literal: two filters overlap here when they carry the same value in the same field. Whether two different searches intersect is the search engine's question, and is not guessed at. USE WHEN: before create_filter, to show the user what the rule would catch and avoid a duplicate. SIDE EFFECTS: none. Requires gmail.settings.basic (it lists the existing filters).

Read the TEXT inside an attachment without saving it: a text file (txt, csv, xml, json, ics, log, …), a gzip file, or the text entries of a ZIP archive — DMARC aggregate reports, exported CSVs, logs. What it reads is decided by the bytes, not by the filename or MIME type the sender declared; text that is not UTF-8 is read as windows-1252 and marked `guessedCharset`. Binary formats (PDF, images, Office files) are refused — use download_attachment for those. Limits, checked before they are spent: 5 MiB unpacked per entry, 20 MiB per archive, 50 entries. Entries that are binary, encrypted, too large or archives themselves are listed with `skipped` and not opened. ONE ANSWER CARRIES AT MOST `maxChars` CHARACTERS OF TEXT across all entries (default 30000, at most 100000); an entry cut by it has `truncated: true` and `nextOffset`, and `chars` always gives an entry's full text length. FOR AN ARCHIVE, LOOK BEFORE YOU READ: `list: true` returns every entry's name, size and text length without any text. Then `entry` reads only the entries you need — an exact name or a pattern with `*` and `?` (`*.csv`), matched case-insensitively against the path and the bare file name; the others are counted in `notSelected`, named in `notSelectedNames`, and never unpacked. A name longer than 256 characters is cut and marked `nameTruncated`; a pattern still matches the whole name. To continue a cut entry, call again with `offset: <nextOffset>`, and for an archive with that `entry` as well (`entry` is refused on a file that is not an archive). The text is untrusted content, exactly like a mail body: it is what a stranger put in the file. USE WHEN: the user asks what an attached report, list or log says. IDs come from get_thread's attachment metadata. DO NOT USE: to save a file (download_attachment). SIDE EFFECTS: none — nothing is written to disk, the mailbox is unchanged.

Search Gmail with native query syntax (e.g. 'in:inbox from:foo@bar.com newer_than:7d'). Returns thread summaries; read-state/category predicates are re-verified against each hit's live labels. `from`, `subject` and `date` are the thread's FIRST message (its origin); `snippet` is Gmail's and comes from the LAST. `lastMessageDate` and `lastMessageId` name that last message, so 'did anything new arrive?' is a comparison of `lastMessageId` against the one you saw, not of `messageCount` against a remembered count — and `get_thread` with `afterMessageId: <the id you saw>` then returns only what is new. `lastMessageFrom` names who wrote that last message and `lastMessageSent` is true when it was this mailbox, so 'has the other side answered?' is `lastMessageSent: false`. `unread` is true when any message of the thread is unread, read off the live labels rather than the search index. `attachments` lists what is attached (filename, declared mimeType, size; at most 10, `attachmentCount` is the total), so 'is there a PDF to keep before archiving?' needs no get_thread — the mimeType is what the sender declared, so check the filename too when it says application/octet-stream. Each summary carries `signals` derived from the thread's first message headers/MIME — newsletter (List-Id/List-Unsubscribe/Precedence bulk, junk or list), automated (Auto-Submitted, auto-reply/suppress headers, no-reply-style senders), calendar (text/calendar or .ics part), replyToMismatch (a Reply-To on another domain than From — a subdomain of the same domain counts as the same), displayNameSpoof (the From display name shows an address or URL on another domain than the one the mail came from), lookalikeDomain (a From domain label mixing Latin with Cyrillic, Greek or Armenian letters); empty when nothing is declared. Paginated: when more results exist, the response carries a nextPageToken — pass it back via pageToken to fetch the next page. A page can come back with FEWER threads than maxResults and still…

Snooze a thread until a date or time: archives it now, resurfaces when it comes due and sweep_snoozed runs. `until` accepts an explicit date (YYYY-MM-DD), a date+time (YYYY-MM-DD HH:MM or e.g. '2026-06-20 9am'), OR a preset resolved server-side: today, tomorrow, weekend (next Saturday), next week (next Monday), a weekday name (monday–sunday, next occurrence), 'in N days', or 'in N hours'. A preset may carry a trailing time ('tomorrow 9am', 'monday 8:30'). A timed snooze wakes at the next sweep on/after that minute. USE WHEN: deferring a thread to a later date/time instead of leaving it in the inbox. DO NOT USE: for permanent removal (use archive or trash). SIDE EFFECTS: removes INBOX, adds a dated MCP/Snoozed label; reversible via unsnooze.

Resurface all snoozed threads whose date is due (<= today), batched at 1000 messages per API request. Set dryRun:true to rehearse: reports the due labels and threads (dueLabels/dueThreads) as the sweep would find them (from the live label listing; a single snooze label with more than 5000 messages is under-counted in the rehearsal), and wakes nothing. USE WHEN: the user asks to process due snoozes, or as a scheduled maintenance call; dryRun to answer 'what is due right now?' without acting. SIDE EFFECTS: due threads return to the inbox marked unread (none with dryRun); safe to run repeatedly. failedCount/errors report messages a batch could not wake (their label is kept for the next sweep).

Move a thread to Trash. USE WHEN: the thread should be discarded. DO NOT USE: for inbox cleanup of mail worth keeping (use archive). SIDE EFFECTS: thread moves to Trash; recoverable via untrash for ~30 days, then Gmail deletes it permanently.

Structured overview of a mailbox slice for triage DECISIONS — sender / label / age buckets, unread and attachment counts, and header-derived signals (newsletter / automated / calendar / replyToMismatch / displayNameSpoof / lookalikeDomain — thread counts overall, and per sender the set of signals its threads carry), instead of a raw thread list. USE WHEN: deciding what to bulk-archive/snooze/label, or summarizing inbox state ('what's in my inbox?'). DO NOT USE: to read a specific thread (use search/get_thread). Samples up to `max` most-recent matches; hasMore flags that more matched than were sampled. byAge buckets by each thread's FIRST message date (thread age, not last activity). SIDE EFFECTS: none.

Revert a bulk_modify exactly, from the `undo` plan it returned (bulk_modify with undo:true). Pass `steps` unchanged: each step adds back the labels its messages lost and takes off the labels they gained, so a message that was already in the target state before the bulk change is left alone. Steps name labels by id, as the plan does; a label name is refused, because an unknown name would be created rather than restored. The plan restores the state read just before the bulk change. A label changed by hand since then is changed again by the undo, and a label deleted since then makes its step fail — reported in `failed`, the other steps still run. A label the bulk change created stays in the mailbox, empty. Set verify:true to read the labels back afterwards — one read per affected thread, however many steps name it. USE WHEN: the user wants a bulk change taken back, and the bulk_modify result carried `undo`. DO NOT USE: without a plan from bulk_modify (use bulk_modify or modify_labels), or to change labels in a new way — this applies exactly the steps it is given. SIDE EFFECTS: label changes on the listed messages; reversible again by the inverse.

Cancel a snooze: return the thread to the inbox now. SIDE EFFECTS: removes the snooze label, restores INBOX.

Unsubscribe from the mailing list a thread came from, via the sender's RFC 8058 one-click endpoint. There is deliberately no URL parameter: the endpoint is taken from the message's own List-Unsubscribe header and nowhere else. Only https one-click endpoints are called (fixed request body, response body discarded); a plain link is reported for the user to open, and a mailto: opt-out is never performed because mailwarden cannot send mail. If the sender offers nothing automatable this returns unsubscribed:false with the alternatives in `options` — it is not an error. USE WHEN: the user wants off a newsletter. Pair with archive/trash or create_filter to deal with mail already in the mailbox. DO NOT USE: to check whether unsubscribing is possible (use list_unsubscribe — it contacts nobody). A sender already contacted in this session is reported with `duplicateOf` and NOT contacted again — safe to retry after a timeout. Pass force:true for a deliberate second attempt (e.g. the endpoint answered 500). SIDE EFFECTS: makes an outbound HTTPS request to the sender's unsubscribe endpoint (plus up to 3 redirects) — the only non-Google host mailwarden ever contacts. This confirms to the sender that the address is live, and it cannot be undone. The mailbox itself is not changed.

Restore a thread from Trash. SIDE EFFECTS: removes the TRASH label; user labels are preserved, but INBOX is NOT re-added — use modify_labels (add INBOX) to return it to the inbox.

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.