| name | inbox-cleanup |
| description | Run a high-recall, multi-pass email inbox cleanup. Pattern-based subject queries catch 25x more archivable email than sender scans alone. Includes urgency triage, classification signals, and post-cleanup filter setup. |
| compatibility | Designed for Vellum personal assistants |
| metadata | {"icon":"assets/icon.svg","emoji":"📭","vellum":{"category":"email","display-name":"Inbox Cleanup","includes":["gmail"],"activation-hints":["When the user asks to clean up, organize, or triage their email inbox","When the user wants to archive old or unwanted emails in bulk","When the user asks to set up email filters to prevent inbox clutter"],"avoid-when":["When the user wants to read, send, or draft a specific email","When the user is setting up email OAuth or connecting a new provider"]}} |
Inbox Cleanup Skill
A playbook for large-scale email inbox cleanup. The core insight: sender-based scans are low-recall. Subject/body pattern queries catch 25x more archivable email. This skill is a multi-pass pipeline built around that insight.
Works with any connected email provider. Adapt query syntax to whatever the provider supports — the strategy (what to search for, how to decide what to archive) is universal.
Gmail is a required integration. It's declared via includes: ["gmail"] in the frontmatter so it loads synchronously on activation, not lazily after the preferences form. Load/confirm the Gmail integration the moment this skill activates — before Phase 1 — so a missing or unauthorized connection surfaces up front rather than mid-cleanup.
Phase 1: Preference Capture
Do this before touching anything. Ask the user:
1. Aggressiveness level
- Conservative — newsletters with unsubscribe headers + obvious spam only
- Standard — above + cold outreach heuristics (subject patterns, unknown senders)
- Aggressive — above + anything from senders with no prior thread history
2. Age threshold
Archive everything older than X days? Common choices: 30 / 60 / 90 days. Or no age filter.
First-run scope: On first invocation, scope to last 30 days or top 3 noise patterns, whichever surfaces faster. Show result, offer to expand. Prove the approach on a fast, visible slice before draining the whole backlog.
3. VIP senders to protect
Ask: "Are there any senders that might look like cold outreach but you actually care about? Think: specific individuals at investors, advisors, your lawyer, accountant, recruiters you're actively working with."
Build an explicit keep list. Do not archive anything matching it, ever, regardless of aggressiveness.
4. Categories to confirm before archiving
These need a sample + explicit approval before bulk action:
- Financial/billing alerts
- Legal/contracts
- Account suspension notices
- Government/regulatory
Phase 2: Urgency Triage (do this before any archiving)
Scan the inbox first for high-stakes items that should be surfaced, not archived. Look for:
| Signal | Why it matters |
|---|
| "past due", "overdue", "final notice", "balance due" | Outstanding invoice — financial consequence |
| "will be suspended", "account suspension", "service interruption" | Service shutoff — operational consequence |
| "collections", "case #", "recovery" in sender domain | Collections agency — credit/legal consequence |
| "signature required", "agreement", "DocuSign pending" | Legal action needed |
| Government TLDs (.gov), "IRS", "state of", "department of" | Regulatory — can't be skipped |
Surface these to the user before running the cleanup. They're easy to miss buried in a big inbox.
Phase 3: The Query Pipeline
Run these passes in order. Each pass should paginate to exhaustion (keep fetching while more results exist). After each pass, show the user a count + 5 sample subjects before archiving anything.
Pass 1: Age-based bulk (biggest catch)
Search for all inbox messages older than the user's age threshold (e.g. 30 days). Typically 50–80% of the archivable backlog. Always show a sample before bulk archiving.
Note on result caps: Some providers cap query results (e.g. ~5,000). If a query returns exactly at the cap, archive that batch and re-run the same query — the next batch will surface. Repeat until it returns fewer than the cap.
Pass 2: Personalized cold outreach (subject patterns)
Ask the user for their first name and company name, then search for subject lines containing patterns like:
[FirstName] -, [FirstName],, for [FirstName], hi [FirstName], hey [FirstName], [FirstName] |[CompanyName] -, [CompanyName]?, for [CompanyName], re: [CompanyName], [CompanyName] AI
These are the highest-recall patterns for cold outreach and partnership spam. A startup founder's inbox will see the biggest wins here.
Pass 3: Generic cold outreach phrases
Search for subject lines containing:
- "quick question", "quick note", "checking in"
- "following up", "just following up", "circling back"
- "would love to connect", "15 minutes", "quick call"
- "intro call", "reaching out", "came across your"
- "are you the right person", "happy to hop on"
Pass 4: No-reply & newsletters
Search for:
- Messages from noreply/no-reply/donotreply sender addresses
- Subject lines containing "unsubscribe", "newsletter", "weekly digest", "monthly digest"
Pass 5: Calendar noise
Search for subject lines containing:
- "accepted:", "declined:", "tentative:"
- "has accepted", "has declined", "invitation:"
Calendar response confirmations are pure noise. Safe to bulk archive without review.
Pass 6: Transactional/receipts
Search for subject lines containing:
- "your order", "order confirmation", "your receipt"
- "shipment", "has shipped", "delivered"
Cross-check against urgency triage first — filter out any "past due" or "final notice" items before archiving this batch.
Pass 7: Sketchy TLDs
Search for messages from sender domains ending in .shop, .biz, .xyz, .info, .club, .online.
Disproportionately spam. Safe to bulk archive.
Pass 8: High-volume repeat senders
After the above passes, run a sender frequency count on what remains. Any sender with 3+ emails not on the keep list is a candidate for bulk archive. Show grouped list to user for approval.
Phase 4: Cold Outreach Classification
For emails not caught by pattern queries, use LLM-based classification in Standard/Aggressive mode. Flag as cold outreach if 3+ signals are present:
- Sender domain not in user's contact/thread history
- No prior reply from user to this sender
- Subject contains user's name + company together (personalization ≠ trust)
- Body contains: "came across your company", "I help companies like", "reaching out because", "15 minutes", "quick call", "are you the right person"
- Sender domain is a known outreach tool:
apollo.io, outreach.io, lemlist.com, instantly.ai, salesloft.com
- Email is not a reply (no
Re: prefix, no quoted text from user in body)
Dry-Run Defaults
Every bulk archive previews before it executes — regardless of batch size or trust stage. Run the pipeline with --dry-run on all archive calls, then render a ui_show table preview the user commits or refines from. Never archive in bulk straight from a query.
The preview table must show:
- Total emails matching — the full count this bulk archive would touch
- Top-10 sender breakdown — senders by volume, so the user spots anything they care about
- 10–20 sample subjects — a representative spread, not just the first few
- Categories flagged for confirm-before-archive — the Phase 1 categories (financial/billing, legal/contracts, account suspension, government/regulatory) that matched, called out for explicit approval
Surface "things worth flagging before you confirm" inside the preview, not after. If the dry-run catches claim documents, failed-payment notices, or any urgency-triage signal (Phase 2), call them out in the preview so the user sees them while deciding — never let a flag-worthy item get archived first and surfaced afterward.
After rendering the preview:
- Ask the user to confirm or refine: "This would archive X,XXX emails across Y passes. Commit, or refine the scope?"
- If confirmed, commit via
bun run scripts/gmail-commit.ts commit --run-id "<run-id>"
- If rejected, cancel via
bun run scripts/gmail-commit.ts cancel --run-id "<run-id>"
Larger batches (e.g. >1,000 operations) and lower trust stages (stage 0 flag-only) warrant extra scrutiny in the preview, but the preview itself is always required before any bulk archive — including small batches and high trust stages. Direct archives are still logged for audit/reversal.
Error Recovery & Resume
Archive operations are logged to an operation log for resumability. If a pass fails mid-run (rate limit, daily quota, OAuth expiry, crash):
- Check for interrupted runs before starting a new cleanup:
bun run scripts/gmail-runs.ts list. If a recent run shows status: "interrupted", offer to resume it.
- Resume:
bun run scripts/gmail-archive.ts archive --resume "<run-id>". This skips already-committed chunks and retries pending ones.
- Daily quota (403): The archive script detects daily quota exhaustion and writes an
interrupted log entry with a resume hint. Do not retry until after midnight PT — offer to resume the run later.
- Rate limit (429): Handled automatically with exponential backoff (up to 5 retries for batch operations). No user intervention needed.
All archive outputs now include a run_id. Pass --run-id to group multiple passes under one run, and --phase to label the pipeline phase (e.g. --phase "noise_archive").
Phase 5: Post-Cleanup
- Report totals — how many archived per pass, which categories, and the
run_id for each pass
- Update blocklist — remember which senders/domains were archived; use for faster future passes
- Surface any urgents found — if financial/legal/suspension items surfaced during the pass, present them now with recommended actions
- Mention reversal — remind the user: "If any of these archives were wrong, I can reverse specific threads:
bun run scripts/gmail-reverse.ts --run-id <id> --thread <message-id>"
Phase 6: Permanent Filter Setup
After cleanup, propose Gmail filters so the same categories don't re-accumulate. This bridges cleanup (drain backlog once) and inbox-management (keep inbox clean on schedule).
Note: Filter creation capabilities vary by provider. The gmail-auto-filters.ts script handles Gmail. If the provider doesn't support programmatic filter creation, give the user manual instructions instead.
Filters are permanent behavior changes. Unlike a one-time archive, a filter silently skips the inbox for every future matching email. A wrong filter means the user misses emails they were expecting — with no indication anything happened. Always confirm with the user before creating filters.
Which patterns are safe as permanent filters
One-time bulk archiving and permanent auto-archiving are different risk levels. The auto-filter script only derives candidates from patterns marked "Yes" below:
| Pattern | Safe as permanent filter? | Notes |
|---|
| noreply / no-reply / donotreply senders | Yes | Automated senders, never personal |
| Calendar responses (accepted/declined in subject) | Yes | Pure noise |
| Specific spam domains identified during cleanup | Yes | Domain-level, not pattern-level |
| Sketchy TLDs (.shop, .biz, .xyz, .info) | Yes | High spam signal, low false positive risk |
| Known newsletter senders confirmed during cleanup | Yes | User just explicitly confirmed unwanted |
| Generic phrases ("quick question", "checking in") | Risky | Real colleagues use these — don't filter |
| Name/company subject patterns ("for [Name]", "[Company] -") | No | Too broad — will catch real emails |
| Age-based | No | Not generally supported as a filter condition |
Running auto-filter generation
After the cleanup pipeline completes (Phase 5 post-cleanup report), invoke:
bun run scripts/gmail-auto-filters.ts preview --run-id "<cleanup-run-id>"
bun run scripts/gmail-auto-filters.ts generate --run-id "<cleanup-run-id>"
If --run-id is omitted, the script finds the most recent completed cleanup run automatically.
The script:
- Reads the cleanup run's op-log to extract archived patterns
- Derives filter candidates from safe categories only
- Fetches existing Gmail filters and skips duplicates
- Shows the user a confirmation dialog listing every filter that will be created, its criteria, and its label — the user must explicitly approve before any filter is created
- Creates one filter per logical category with an
auto/* label (e.g. auto/no-reply, auto/calendar, auto/newsletter, auto/sketchy-tld)
- Logs all filter creations to the op-log for audit and reversal
Label strategy
Every auto-filter applies an auto/* label instead of silently archiving. This gives the user an audit trail — search label:auto/calendar to see what was caught. Labels are created automatically if they don't exist.
After filter creation
Tell the user:
- How many filters were created and what each covers
- How to find auto-archived emails (search by label, e.g.
label:auto/no-reply)
- How to remove a filter:
bun run scripts/gmail-manage.ts filters --action delete --filter-id "<id>"
Reference: Proven Catch Rates
From a single cleanup session on a startup founder's inbox (April 2026):
| Pass | Approx. catch |
|---|
| Older than 30 days | ~7,200 |
| Name-personalized subject patterns | ~35,000 |
| Company-name subject patterns | ~50,000 |
| Sketchy TLDs (.shop/.biz/.xyz) | ~3,741 |
| Newsletters/digests | ~1,014 |
| Calendar responses | ~142 |
| Generic cold outreach phrases | ~23 |
| Completed DocuSigns | ~34 |
Total: ~90,000+ emails in one session. The name/company pattern passes alone accounted for ~85k. This is why patterns dominate sender scans.
