Use the skill
Give it to Claude Code, Cursor, OpenCode or another agent with shell access. It reads headers only, shows the plan first, and gives you the undo command.
Open the skillOr and paste it in Claude Code, Cursor or OpenCode.
Open source · Agent skill · Local app
Clean up your inbox.
Undo every move.
CleanYourMail is an open-source agent skill for IMAP cleanup, with an optional local app. It reads headers only, shows you a plan before anything changes, protects important mail, and gives you the undo command. Unsubscribe stays separate and irreversible.
Free · MIT · No account · No telemetry · No permanent deletion
AGENT SKILLMain product
Give it to your agent.
Read SKILL.md from
https://github.com/jparedesDS/cleanyourmail
and follow it exactly.
Use python tools/mail.py.
Headers only. Never permanently delete.
Show me the plan before changing anything.
Move first, verify, then unsubscribe separately.
Give me the undo command.Paste it in Claude Code, Cursor, OpenCode or any agent with shell access.
Skill first · app optional · CLI on GitHub
Choose your path
Use the skill, or the app.
The skill is the main product: give it to your coding agent and review the plan. The app is the simple path for people who prefer buttons. The CLI is still on GitHub for power users.
App · Early MVP
Download the app
A local, secure app for people who prefer buttons over prompts. Scan headers, review the plan, apply reversible moves and undo from one screen. No account, no telemetry; feedback is opt-in.
Download for WindowsWindows 10/11 · installer · early MVP
Prefer the terminal? The CLI is still on GitHub.
How it works
Nothing changes until you approve a plan.
-
01
Connect locally
Open the skill in your agent, or use the app. Choose your provider and enter your credential. It tests the connection before anything else.
-
02
Scan and review
The skill or app reads header metadata only: sender, subject, date, size and flags. It shows categories, protected mail, destinations and unsubscribe targets. Nothing changes yet.
-
03
Move a small batch
Apply a few moves. The journal records the run and Undo restores it. Review the result before handling unsubscribe separately.
Providers
Works with your provider.
No migration. You need IMAP access and the authentication method your provider allows.
GmailApp Password + 2FA
Outlook / Microsoft 365Microsoft 365: admin consent
YahooApp password
iCloudApp-specific password
FastmailApp password + Sieve
ProtonProton Bridge
Any IMAP server with UIDPLUS or MOVE and resolvable Trash, Junk and Archive works. Provider notes · validation status.
Provider names and logos are trademarks of their respective owners.
Safety
Review first. Undo the moves.
No permanent deletion
There is no permanent-delete command. CleanYourMail never empties Trash or Junk and never runs a mailbox-wide expunge.
Headers only
It reads sender, subject, date, size, flags and unsubscribe headers, and stores that metadata locally. It never downloads bodies or attachments.
Protected mail stays put
Personal, transactional, security, banking, invoice, travel, medical, government, legal, starred, answered and recent mail is excluded from automatic moves and unsubscribe requests.
Review, move, undo
scan, report and plan change nothing. Review the plan, start with a small move, and use the journal and undo to restore that run. Unsubscribe is separate and irreversible.
Runs locally: no hosted CleanYourMail service, no account, no telemetry. Inspect the code, the safety model and the tests.
FAQ
Questions before you connect.
Does it delete email?
No. It has no permanent-delete command, never empties Trash or Junk, and never runs a mailbox-wide expunge. Moves and archives are journaled; unsubscribe requests are not reversible.
What does it read?
Headers only: sender, subject, date, size, flags and unsubscribe headers. It never downloads bodies or attachments. The local cache stores metadata, not message bodies.
Do I need to be technical?
The app is the simple path. The skill, the main product, needs a coding agent with shell access. The CLI is for developers who prefer the terminal. All three use the same plan and undo model.
Does it work with my provider?
Gmail, Outlook/Microsoft 365, Yahoo, iCloud, Fastmail, Proton Bridge and compatible custom IMAP servers. Gmail needs an App Password with 2-Step Verification; Microsoft 365 sign-in requires tenant admin consent; personal Outlook.com requires a verified publisher (pending); Proton needs Bridge. Custom IMAP moves require UIDPLUS or MOVE. Provider or tenant policies may block access; the tool does not bypass them.
What happens if something goes wrong?
Stop and inspect the error. The skill, the CLI and the app re-check the plan before applying it and record each run. Use the printed undo command to restore that run’s moves. If a message cannot be found, the journal remains for manual recovery. Unsubscribe requests cannot be undone.
Is it really free?
Yes. MIT-licensed, no paid tier, no CleanYourMail account and no telemetry. You provide your computer, Python installation and mail-provider access.
Feedback
Tell us what to fix.
Found a bug or have an idea? Send it to the CleanYourMail Discord. Nothing is sent automatically: write the details, accept the consent line and press Send. Remove anything you do not want to send, and never include passwords, tokens or full message contents.
Start with a plan.
Change nothing until you say yes.
Free and open source. No account, no telemetry and no permanent deletion.