Smart Email Triage
Automate Gmail inbox organization with intelligent classification into newsletters, announcements, expenses, and auto-archive categories.
You have 3,000 unread emails because newsletters, receipts, and notifications bury the messages that actually need your attention. This playbook automates Gmail inbox triage — classifying emails into actionable categories and auto-archiving noise so you only see what matters.
Who it's for: executives drowning in email who need to surface only high-priority messages, entrepreneurs managing multiple business email streams without an assistant, professionals pursuing inbox zero by automating the sorting they currently do manually, remote workers whose inboxes mix personal and work communications, freelancers managing client emails alongside marketing newsletters and notifications
Example
"Set up smart email triage to get my inbox under control" → Email triage pipeline: Gmail API integration with classification rules for newsletters, receipts, notifications, and action-required emails, automatic label and archive rules for low-priority categories, daily digest summary of archived items, priority inbox surfacing only emails needing human response, and weekly email analytics showing volume by category
New here? 3-minute setup guide → | Already set up? Copy the template below.
# Smart Email Triage
## Your Role
You intelligently classify Gmail emails into labeled categories using header analysis, body scanning, domain patterns, and scoring thresholds — while protecting VIP contacts from auto-triage.
## Required
- Gmail MCP integration
- Config files at `~/.claude-assistant/config/`
## Arguments
- `noapply` — preview classifications without applying labels
- `days:N` — override search window (e.g., `days:14`)
- `limit:N` — process only first N emails
## Instructions
### Phase 1: Load Configuration
Read `triage-config.md` and `email-policy.md` from `~/.claude-assistant/config/`.
### Phase 2: Label-in-Inbox Sweep
Find emails that already have triage labels but are still in inbox — archive them.
### Phase 3: Calculate Search Window
Determine lookback period based on last run timestamp. Use `days:N` if specified.
### Phase 4: Search Inbox
Two queries: unread general emails + all potential expenses (including read).
### Phase 5: Deduplicate
Skip emails processed in previous runs (check state file).
### Phase 6: Fetch Email Content
Retrieve headers and body for each email.
### Phase 7: VIP Protection
Skip classification for Tier 1 and Tier 2 VIP contacts. These always stay in inbox.
### Phase 8: Expense Detection
Route receipts based on vendor domains, subject keywords, and routing table:
- Known vendor domains → Expenses-Pending or Expenses-Personal
- Uncertain matches → Expenses-Uncertain
### Phase 9: Filter Bypass Recovery
Check against documented Gmail filters — apply missed filter actions.
### Phase 10: Calendar Detection
Identify meeting invitations (calendar- prefix, "Invitation:" subject, text/calendar content).
### Phase 11: Classification Logic
Score remaining emails:
| Signal | Points |
|--------|--------|
| List-Unsubscribe header | +2 |
| "unsubscribe" in body | +2 |
| noreply/no-reply address | +1 |
| Generic greeting | +1 |
| Newsletter platform domain | → @ToRead directly |
| School domain | → @School directly |
Apply thresholds: Newsletter >=3, Announcement >=2.
Use classification priority table for tiebreakers.
### Phase 12: Generate Report
Show proposed actions before applying:
```
TRIAGE REPORT
━━━━━━━━━━━━
@ToRead: [N] newsletters
@Announcements: [N] institutional
@School: [N] academic
Expenses: [N] receipts
Auto-Archive: [N] notifications
Skipped (VIP): [N] protected
```
### Phase 13: Apply Labels (skip if noapply)
Apply labels and archive per routing rules. Never fire parallel batch operations.
### Phase 14: Update State
Log processed message IDs and timestamp.
## Label Application Rules
- @ToRead: Add label, remove INBOX, leave UNREAD
- @Announcements, @School: Add label, remove INBOX, leave UNREAD
- Expenses-Pending/Personal: Add label, remove INBOX, mark READ
- Expenses-Uncertain: Add label, remove INBOX, leave UNREAD
- Auto-Archive: Add label, remove INBOX and UNREAD
## Critical Rules
- Never reclassify emails already bearing Expenses-* labels
- VIP contacts are NEVER auto-triaged
- Never fire multiple batch operations in parallel
What This Does
Goes beyond Gmail's native filters to intelligently classify emails into labeled categories — newsletters, announcements, expenses, school notices, and auto-archive candidates. Uses header analysis, body scanning, domain patterns, and scoring thresholds with VIP protection for important contacts.
Prerequisites
- Gmail MCP integration configured in Claude Code
- Two config files (setup guide below)
Quick Start
Step 1: Set Up Config Directory
mkdir -p ~/.claude-assistant/config ~/.claude-assistant/state ~/.claude-assistant/logs
Step 2: Get Your Gmail Label IDs
Run in Claude Code: "List my Gmail labels and their IDs"
Step 3: Create Config Files
Create ~/.claude-assistant/config/triage-config.md with your label IDs, vendor domains, and thresholds.
Create ~/.claude-assistant/config/email-policy.md with your VIP contact lists and archive rules.
Step 4: Download the Template and Test
Click Download above, save to your working directory, then:
"Triage my inbox — preview only"
Classification Categories
| Category | Label | Read State | Archived? |
|---|---|---|---|
| Newsletters | @ToRead | Unread | No |
| Announcements | @Announcements | Unread | Yes |
| School notices | @School | Unread | Yes |
| Expense receipts | Expenses-Pending | Read | Yes |
| Personal expenses | Expenses-Personal | Read | Yes |
| Uncertain expenses | Expenses-Uncertain | Unread | Yes |
| Auto-archive | Auto-Archive | Read | Yes |
How Classification Works
- Check overrides — sender-specific routing rules applied first
- Scan headers — List-Unsubscribe (+2), noreply address (+1)
- Scan body — unsubscribe links (+2), generic greetings (+1)
- Check domains — newsletter platforms (Substack, Mailchimp), school domains
- Apply scoring — newsletter threshold (default >=3), announcement (>=2)
- VIP protection — Tier 1/2 contacts never auto-triaged
Config Files
email-policy.md
- VIP Tier 1: Family, compliance senders — always stay in inbox
- VIP Tier 2: Collaborators, team members — always stay in inbox
- Auto-archive rules: Documented Gmail filters as backstop
triage-config.md
- Label IDs: Gmail internal IDs for each category
- Vendor domains: Amazon, Uber, etc. for expense detection
- Scoring thresholds: Adjust classification aggressiveness
- Override table: Sender-specific routing rules
Usage
"Triage my inbox" — Scan and apply labels
"Triage my inbox — preview only" — Preview without applying
"Triage my inbox — last 14 days" — Extended lookback
"Triage my inbox — limit 20" — Process only 20 emails
Smart Features
- Adaptive search windows — adjusts lookback based on when you last ran it
- Classification overrides — sender-specific rules that bypass scoring
- Auto-filter creation — creates Gmail filters for high-confidence patterns
- Deduplication — tracks processed emails to avoid re-scanning
- Expense detection — routes receipts to the right expense category
Tips
- Start with preview mode — run with "preview only" until you trust the classifications
- Build overrides gradually — add sender-specific rules as you spot misclassifications
- VIP list is sacred — important contacts are never auto-triaged
- Run daily or after travel — keeps inbox manageable
Troubleshooting
Emails misclassified Add the sender to the classification overrides table in triage-config.md
Too aggressive archiving Raise the scoring thresholds in triage-config.md
VIP emails getting triaged Add the contact to Tier 1 or Tier 2 in email-policy.md
"Label not found" errors Re-run the label ID retrieval — Gmail IDs can change