GMAIL TRIAGE AGENT
An AI agent that reads, classifies, and drafts replies to every incoming email — running automatically in the background so nothing important gets missed.
Overview
Two main capabilities work together to keep inbox volume under control:
Automated triage runs hourly via cron. It classifies every new unread email, applies Gmail labels, and drafts replies for anything that needs a response — all without sending a single message.
Inbox cleanup utilities are a set of one-off scripts to bulk-unsubscribe from promotions and clear out old emails. Run once to start from a clean state, then let triage keep it that way.
How Triage Works
-
Fetch
On each hourly run, up to 50 unread inbox emails are pulled — only ones not already logged in the processed state file.
-
Classify
Claude Haiku reads each email alongside your existing Gmail labels and 8 recent sent emails for tone matching, then returns a category, a reason, a suggested label, and a draft reply.
-
Label
A
triage/<category>label is applied automatically, plus the suggested user label. Labels are created if they don't already exist. -
Draft
For URGENT and NEEDS_REPLY emails, a draft reply is saved in Gmail — ready to review and send, but nothing goes out automatically.
Categories
| Category | Meaning |
|---|---|
| URGENT | Needs action within hours — deadlines, emergencies, time-sensitive requests |
| NEEDS_REPLY | Should respond within 1–2 days — questions, requests, conversations |
| FYI | Informational, no reply needed — receipts, notifications, newsletters |
| JUNK | Spam, cold outreach, marketing |
Cleanup Utilities
Four standalone scripts to run manually before setting up triage on a cluttered inbox:
| Script | What it does |
|---|---|
| mark_all_read.py | Marks every unread inbox email as read in bulk — useful for clearing a large unread count before starting fresh |
| cleanup_promotions.py | Keeps one email per sender in Promotions and trashes the rest, using batch API calls to handle large inboxes |
| unsubscribe.py | Scans Promotions emails for List-Unsubscribe headers and fires unsubscribe requests; shows a numbered list so you can pick specific senders |
| delete_unsubscribed.py | Trashes all remaining promotion emails from senders where unsubscribe succeeded |
Recommended Workflow
-
mark_all_read.py
Zero out the unread count so triage starts from a clean baseline.
-
cleanup_promotions.py
Deduplicate the Promotions folder, keeping one email per sender.
-
unsubscribe.py
Opt out of everything in bulk.
-
delete_unsubscribed.py
Trash the emails from successfully unsubscribed senders.
-
Set up cron for triage.py
Keep the inbox clean going forward with hourly automated classification and drafting.