triage

Triage a mailbox with mailwarden

The tools are self-describing; this is about the handful of places where the obvious call is the wrong one. Everything below is a property of the tools, not a style preference.

The one rule that prevents lost mail

search re-verifies its hits. bulk_modify does not. search fetches every thread it returns anyway, so it checks each one's live labels against your query and drops the index's false positives. A bulk action is sized in thousands and cannot pay that, so it acts on what Gmail's index returned.

That matters because the index can be wrong about read state in a way that is neither rare nor uniform: in one measured mailbox, category:updates is:unread matched 131 threads through the thread index of which only 17 held an unread message — a bulk archive over that query would have moved 114 threads the user had already read. Another mailbox, measured the same day, drifted not at all. A server cannot tell which kind of mailbox it is in, and neither can you.

So:

• Every bulk_modify result carries unverifiedPredicates. Empty means the query had no condition worth distrusting — proceed. Non-empty (+UNREAD, -INBOX, …) means those conditions rest on the index alone.
• When it is non-empty and a wrong hit would matter — anything the user would notice or cannot easily undo — resolve the set with search first and act on the thread ids it returns.
• dryRun: true does not close this gap. It re-reads the same index, so it confirms how big the set is, never whether it is right. Use it for size, not for correctness.
• crossCheck: true is the cheap middle option: it re-asks each predicate as a label filter and drops messages the two routes disagree about, for one extra list call per predicate. Read a disagreement as real and agreement as nothing — both routes read the same index.

Reporting what actually happened

bulk_modify returns submittedMessages, and that is the count of ids handed to the API. Gmail's batchModify answers with no body and ignores ids it does not recognise without a word, so an accepted request is not a performed one. Do not tell the user that N messages were archived on the strength of that number. Pass verify: true when the outcome will be reported as done or cannot be easily reversed, and quote verified.applied — the only field that reports something observed.