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.
• create_filter with applyToExisting carries no unverifiedPredicates at all — do not read its absence as an empty list. The sweep's query is built from your criteria, and the way it is built (parentheses around a query criterion, quotes around every address or subject) switches the derivation off for every filter that can be defined, so the field would be empty even where the criteria do rest on read state. Treat a sweep as acting on the index's answer, always. When the set has to be right before anything is written, resolve it with search and use bulk_modify on those thread ids instead — then create the filter for future mail.