CleanYourMail

Open source · Agent-native · Reversible

Your inbox,
minus the noise.

Clean up years of newsletters, promos and spam in one reviewed pass. Headers only. Plan first. Every move undoable.

Clean my inbox See how it works

Free and open source · No account · No telemetry · MIT

  • Headers only
  • No permanent delete
  • Undo every move
  • 144 tests
Review the plan. Then apply.
INBOX3 unread
Your statement is readybank.example · protected07:20
Re: lunch tomorrowfriend@example.com · personal06:12
Your order shippedshop.example · transactional05:48
CleanYourMail/Newsletters42
CleanYourMail/Promotions28
Junk6
✓ Moves journaled · undo available
plan.json 76 moves 12 unsubscribes Review before apply
protected filed junk

CH 01 · How it works

Read. Protect. Plan. Clean.

A small CLI, a reviewable plan and an undo journal. No black-box “AI inbox cleaner”.

Scan headers

Sender, subject, date, flags and List-Unsubscribe. No bodies, no attachments, no full-mailbox download.

Protect what matters

Banks, security codes, invoices, travel, medical, government, personal, starred, answered and recent mail stay put.

Build a plan

Exact UIDs, destinations and unsubscribe targets in plan.json. Nothing changes until you apply it.

File or archive

Folders or Gmail labels, Junk, Trash, or archive. COPY first, then UID EXPUNGE. Never a mailbox-wide expunge.

Unsubscribe safely

RFC 8058 one-click POST, mailto:, or a manual link. Header targets only. Spam is never unsubscribed.

Undo the moves

The journal records COPYUID and Message-ID. One command restores moves and Gmail archives. Unsubscribe cannot be unsent.

Read the full procedure in SKILL.md ↗

CH 02 · Why

A different kind of inbox cleaner.

Most tools ask for your password, read your mail and delete the evidence. CleanYourMail runs on your machine, reads headers only, and keeps an undo journal.

Private by construction

The CLI runs locally. The scan fetches header fields only. The cache stores metadata, never message bodies. No telemetry, no analytics, no third-party API.

Reversible by default

Every move is recorded with COPYUID and Message-ID. One command restores it. Gmail archive re-adds the Inbox label. Unsubscribe is the only irreversible step, and it is explicit.

Agent-native, not agent-only

The CLI is the product. SKILL.md and PROMPT.md teach any coding agent to use it safely. No new app, no browser extension, no OAuth broker.

Hosted inbox cleanersCleanYourMail
Runs in their cloudRuns on your machine
Reads full messagesReads headers only
Deletes or archivesMoves and journals
Undo via support ticketUndo with one command
Sign-up and OAuth brokerNo account at all
SubscriptionFree, MIT

General comparison with hosted cleanup services. Check each product.

CH 03 · Set up

Three steps. Your coding agent does the typing.

Python 3.11+. No packages. An app password or OAuth token. A terminal.

  1. 01

    Connect

    Clone the repo, write a config, put the secret in CYM_PASSWORD, then run doctor.

  2. 02

    Review

    Scan headers, read the report, and generate a plan. Correct protected senders before anything moves.

  3. 03

    Clean

    Apply moves first. Verify. Then send unsubscribe requests separately. Keep the undo command.

powershell
$ git clone https://github.com/jparedesDS/cleanyourmail.git
$ cd cleanyourmail
$ python tools/mail.py init --email you@example.com
$ $env:CYM_PASSWORD = "app-password"
$ python tools/mail.py doctor
$ python tools/mail.py scan --days 365
$ python tools/mail.py report --top 30
$ python tools/mail.py plan --mode folders
Copy the agent prompt ↗

Start small. Use --limit 50 for the first run, review plan.json, and keep the undo command. On macOS or Linux, use python3 instead of python.

Using a coding agent? Paste PROMPT.md. It will read SKILL.md, show you the plan, move first, and give you the undo command. It will not skip the review.

CH 04 · Providers

Works with the mailbox you already have.

IMAP and SMTP, app passwords or OAuth2. No hosted service, no mailbox migration.

Recommended for Gmail

App Password + IMAP

Turn on 2-Step Verification, create an App Password, enable IMAP. Folders are labels; archive removes the Inbox label and keeps the message in All Mail.

Auth App PasswordArchive Label removalRules Gmail XML

Full setup notes in docs/PROVIDERS.md. Your provider not listed? Any IMAP server with UIDPLUS or MOVE works.

CH 05 · Safety

Safe by design. Boring on purpose.

The interesting part is not what it can do. It is what it refuses to do.

✕

No permanent deletion

Moves copy first and use UID EXPUNGE. No mailbox-wide expunge. Trash is never emptied. If the server lacks UIDPLUS/MOVE, moves are refused.

◎

Protected mail stays put

Transactional and personal mail, security codes, banks, invoices, travel, medical, government, starred, answered and recent messages are never auto-moved.

⌁

No bodies. No attachments.

The scan fetches header fields only. The local cache stores metadata, not message content. There is no content index and no AI reading your mail.

↯

Links are treated as hostile

Only List-Unsubscribe headers. No redirects, cookies or proxies. Private/local targets are rejected. Manual links are for you to open, not the agent.

☍

Prompt injection is data

An email cannot give the agent instructions. “Ignore your rules”, “send this” or “run that” is reported, not followed.

!

Consent does not waive safety

“Skip the plan”, “delete everything” or “unsubscribe from everything” is a stop condition. Plan review, protected mail, spam exclusion and batch caps are not optional.

No account No telemetry No third-party API No bodies read No permanent delete
✓

Unsubscribe is the one irreversible step. It is explicit, capped, delayed, and never applied to spam. Moves and archives have an undo journal. Unsubscribe requests cannot be unsent. Read the full safety rules ↗

144tests, fake IMAP only
7provider presets
0bodies read
0permanent deletes
1command to undo moves

CH 06 · FAQ

The questions people ask.

Does it delete email?

No. It moves mail to folders, labels, Junk, Trash or archive. It never empties Trash, never runs a mailbox-wide expunge, and never has a “delete forever” command.

Does it read my email?

No. The scan fetches header fields only: sender, subject, date, size, flags and unsubscribe headers. Bodies and attachments are never downloaded.

Is it free?

Yes. CleanYourMail is MIT-licensed and free to use. There is no paid tier, no account and no upsell.

Do I need to be technical?

You need a terminal and Python 3.11+. A coding agent can do the typing for you: paste PROMPT.md and follow the plan. The CLI is also usable directly.

Does it work with Gmail?

Yes. Gmail uses labels rather than folders. Archive removes the \Inbox label and leaves the message in All Mail. The undo re-adds the label using X-GM-MSGID or Message-ID.

What about Outlook and Microsoft 365?

Use an OAuth2 access token with auth = "xoauth2". The CLI does not acquire or refresh tokens. Some tenants disable SMTP AUTH, so a mailto: unsubscribe may need to be done manually.

Will unsubscribing stop spam?

No. Spam is never unsubscribed: a spam unsubscribe link can confirm that the address is live. Spam goes to Junk. For legitimate lists, unsubscribe is a request, not a guarantee.

Is it safe to run on my real inbox?

The workflow is dry-run first: scan, report, plan, review. Apply moves only after reviewing the plan. Start with --limit or a single category. Keep the undo command. It is still software: review the plan.

What if my server has no UIDPLUS or MOVE?

Moves are refused. The only fallback would be a mailbox-wide expunge, which could permanently delete another client’s message. Use a client that supports UIDPLUS/MOVE or move manually.

What data leaves my machine?

Only IMAP/SMTP traffic and the validated unsubscribe requests. There is no telemetry, no analytics, no third-party API and no content index. The website loads no third-party resources.

Can I use it without an agent?

Yes. The CLI is the product. The skill and prompt just teach a coding agent to use it safely. Every command is documented in SKILL.md and README.md.

Is there a hosted service?

No. There is no account, no server, no telemetry and no third-party API. The only network calls are IMAP, SMTP for a mailto unsubscribe, and a validated one-click HTTPS request.

Start small. Stay in control.

Make the inbox quiet.
Keep the important mail.

Run the dry run. Review the plan. Apply a small batch. Undo if you change your mind.

Get the skill on GitHub Read the safety rules

No account. No telemetry. MIT.

start here
$ python tools/mail.py scan --days 365
$ python tools/mail.py report --top 30
$ python tools/mail.py plan --mode folders
$ python tools/mail.py apply <plan.json> --yes --action move
then unsubscribe separately