Inbox Declutter

AI-assisted inbox cleanup for overwhelming unread backlogs — local-first, review-first, safe at scale.

If this helps you tame your inbox, ⭐ star the repo so others can find it too.

Website: https://mqcoding.github.io/inbox-declutter/

You have 10,000… 50,000… 70,000+ unread emails. Deleting one-by-one is impossible. Blind auto-delete is reckless.

Inbox Declutter scans your inbox in batches, groups mail by sender, classifies it with rules + optional AI, and lets you approve before anything is archived, deleted, or unsubscribed.

One sender decision can clear hundreds of emails.

---

Why this exists

Most inbox tools assume you want full automation. That is scary when years of email might include receipts, legal notices, or something important buried in the noise.

This tool takes a different approach:

1. Cluster by sender — promos from the same store are one decision, not 800
2. Classify intelligently — newsletters, promotions, receipts, action-required, unknown
3. Review first — you approve categories or senders before any bulk action
4. Dry-run by default — preview impact before touching your mailbox
5. Runs locally — scan data stays in a local SQLite database on your machine

Built for people with real backlog pain — including the author, who started with 70K+ unread.

---

Features

• Gmail, Outlook, and IMAP support
• Batch scanning for large backlogs (1K–2K at a time)
• Sender clustering for high-leverage cleanup
• Rule-based classification + optional OpenAI for uncertain senders
• Review queue with approve/reject by sender or category
• Bulk actions: archive, delete, star, mark read, unsubscribe
• Cursor Agent skill for chat-guided cleanup sessions

---

Quick start

git clone https://github.com/mqcoding/inbox-declutter.git
cd inbox-declutter

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
cp .env.example .env

Gmail setup

1. Create a Google Cloud project and enable the Gmail API
2. Create OAuth 2.0 Desktop credentials
3. Download JSON to credentials/gmail_credentials.json
4. Run a scan — your browser opens for one-time auth

See credentials/README.md for details.

First run (recommended for large backlogs)

# Scan + classify + export review report
email-declutter workflow --provider gmail --max-messages 2000

# See what the tool suggests
email-declutter review

# Approve obvious categories
email-declutter approve --category newsletter
email-declutter approve --category promotion

# Preview, then apply
email-declutter apply --dry-run
email-declutter apply --no-dry-run

Repeat in batches until your backlog is under control. Do not try to process 70K emails in one run.

---

How it works

Inbox → Scan batches → Group by sender → Classify → Review queue → You approve → Apply

Step	What happens
Scan	Fetches unread mail metadata + short body preview
Cluster	Groups messages by sender address
Classify	Rules first; OpenAI optional for uncertain senders
Review	You inspect suggestions by sender/category
Apply	Executes approved actions (dry-run by default)

Categories

important · action_required · personal · work · receipts · newsletter · promotion · notification · social · spam · unknown

---

Commands

email-declutter scan --provider gmail --max-messages 1000
email-declutter classify
email-declutter review
email-declutter review --export data/review-report.json
email-declutter approve --category newsletter
email-declutter approve --cluster-id "gmail:you@gmail.com:sender@example.com"
email-declutter reject --category unknown
email-declutter apply --dry-run
email-declutter stats
email-declutter workflow --provider gmail --max-messages 2000

---

Provider support

Provider	Status	Notes
Gmail	Supported	OAuth desktop flow
Outlook / Microsoft 365	Supported	Device-code auth
IMAP	Supported	Yahoo, Proton Bridge, custom domains

---

Safety

• Dry-run is the default for apply
• Nothing is deleted or unsubscribed until you approve clusters
• Start with newsletter and promotion before approving unknown
• All scan data stays local in data/declutter.db
• Credentials and tokens are gitignored — see credentials/README.md

---

Using with Cursor

This repo includes a Cursor skill at .cursor/skills/email-declutter/SKILL.md.

Example prompts:

• "Run the email declutter workflow on my Gmail, first 1000 unread"
• "Summarize the review report and tell me what's safe to bulk-archive"
• "Approve all newsletter clusters and dry-run the apply step"

---

Configuration

Copy .env.example to .env. Key settings:

Variable	Purpose
OPENAI_API_KEY	Optional — improves classification for uncertain senders
GMAIL_CREDENTIALS_PATH	Path to Gmail OAuth JSON
OUTLOOK_CLIENT_ID	Azure app client ID
IMAP_HOST / IMAP_USERNAME / IMAP_PASSWORD	Generic IMAP accounts

---

Roadmap

• Daily digest of important and action-required mail
• Learn from approve/reject decisions
• Gmail label sync
• Simple web dashboard
• PyPI package (pip install inbox-declutter)

---

Contributing

Contributions welcome. If this helped you tame your inbox, a star on GitHub helps others find it too.

1. Fork the repo
2. Create a feature branch
3. Open a pull request

---

Launch / share

Ready to publish? See LAUNCH.md for GitHub setup, suggested repo name, topics, and copy-paste posts for Hacker News and Reddit.

---

Share it

Help others drowning in unread mail find this project:

• ⭐ Star the repo
• 🔗 Share: https://github.com/mqcoding/inbox-declutter
• 🌐 Landing page: https://mqcoding.github.io/inbox-declutter/

Copy-paste launch posts: LAUNCH.md

---

License

MIT — use it, fork it, share it. See LICENSE.