An open-source, local-first Gmail storage cleaner. It finds storage-heavy senders, old recurring mail, and safe archive/trash candidates, while keeping review and reversibility first.
Why I built it
Gmail storage cleanup tools tend to want broad, standing access to your inbox and push you straight to bulk delete. Mail Reclaim scans metadata and headers only (it never downloads full message bodies for the read-only pass), keeps read-only scanning and destructive actions on separate OAuth scopes, and produces conservative recommendations with explicit reason codes instead of a one-click "clean everything" button.
Design goals
- Local first: cache scan data in local SQLite instead of sending mailbox metadata to a hosted service.
- Read before modify: keep the analysis OAuth scope separate from any action scope.
- Reversible by default: support label, archive, and trash paths; avoid permanent delete.
- Explain recommendations: show reason codes so a user can reject the tool's judgment.
What it does
- Connects to Gmail with user-owned OAuth credentials
- Scans metadata and headers without downloading full email bodies
- Ranks senders by count, estimated storage, and risk
- Produces conservative recommendations with reason codes
- Keeps action mode (label/archive/trash) separate from read-only analysis
Safety model
Read-only scanning always comes first. Modify access is a separate OAuth scope used only for label, archive, and trash, never permanent delete. Guardrails protect recent, starred, important, human, finance, legal, medical, immigration, job, receipt, order, travel, and security-related mail from being recommended. Hosted AI is not required; a rules-based risk engine is the default, and it remains the final safety gate for any future AI/ML-assisted suggestions.
Threat model
The main failure I am designing against is not a clever model error. It is ordinary overreach: a cleanup tool sees a large sender, treats it as junk, and removes mail the user later needs. Mail Reclaim therefore treats "do nothing" as the safe default. Protected classes of mail are excluded from recommendations, and action mode is a separate step after review.
The second failure is consent drift. A user may be comfortable with read-only mailbox analysis but not with a tool that can modify mail. Splitting OAuth scopes keeps that boundary visible.
Current status
First development build: read-only OAuth flow, Gmail metadata scan, local SQLite scan cache, rules-based risk engine, browser dashboard, and an action API for label/archive/trash with explicit modify OAuth, ready for guarded UI expansion. AI/ML modes beyond the rules engine are research-gated and not yet locked.
What still needs work
The project needs more guarded UI around bulk review before I would call it ready for casual users. The action API exists, but the review surface should make it easy to inspect sender groups, reason codes, protected classes, and estimated storage before changing anything. I would rather ship that slowly than make a fast inbox cleaner that feels powerful for five minutes and risky after that.
Project artifacts
- Repository with source and setup notes.
- Local SQLite cache and read-only scan path are part of the public implementation direction.
- The project page documents the boundary between current rules mode and future AI/ML-assisted suggestions.
Quick start
uv sync
uv run mail-reclaimOpens a local dashboard at http://127.0.0.1:8765. Full setup in the README.