IMAP Cleanup CLI

imap-cleanup is a command-line tool for inspecting and cleaning up IMAP mailboxes. It reports folder sizes and account quotas, can find and delete messages by date or size, and can delete whole folders.

Requirements

• Python (see version)
• uv
• An IMAP account. App-specific passwords are recommended when your provider supports them.

Install

Clone the repository and install dependencies:

git clone https://github.com/jonlabelle/imap-cleanup.git
cd imap-cleanup
uv sync --dev

Quick start

List all mailboxes sorted by size:

uv run imap-cleanup folders

Credentials are loaded from a .env file or environment variables. See Configuration for setup details.

Commands

• folders — List all mailboxes sorted by size, with optional quota usage.
• delete — Dry-run or mark messages deleted from a mailbox by date, size, or both.
• delete-folder — Dry-run or delete an entire mailbox/folder, optionally including child folders.

See Examples for worked end-to-end usage.

Development

Requires uv. Simply run uv sync --dev to install dependencies and get started.

The CLI is built on imaplib and argparse from the standard library.

Commands

uv sync --dev                # Install dependencies
uv build                     # Build wheel distribution in dist/
uv run ruff check .          # Lint
uv run ruff format --check . # Check formatting
uv run ruff format .         # Format code
uv run mypy .                # Type check
uv run pytest                # Run tests

VS Code

This repository includes VS Code tasks and launch configurations for the local uv workflow.

Useful tasks:

• uv: sync — Install dependencies
• uv: check all — Lint, format check, type check, and run tests
• uv: pytest — Run tests
• uv: ruff format — Format code with Ruff
• uv: build package — Build wheel distribution in dist/
• imap-cleanup: folders — Run the folders command
• imap-cleanup: folders json — Run the folders command with JSON output
• imap-cleanup: delete preview — Preview messages in Archive before 2025-01-01
• imap-cleanup: delete preview json — Preview the same delete filter with JSON output
• imap-cleanup: delete folder dry run — Check the Old Projects folder before deletion
• imap-cleanup: delete folder dry run json — Check the same folder with JSON output
• imap-cleanup: delete folder recursive dry run — Check Old Projects and child folders before deletion

Debug launch configurations:

• imap-cleanup: folders — Run the folders command
• imap-cleanup: folders json — Run the folders command with JSON output
• imap-cleanup: delete preview — Preview messages in Archive before 2025-01-01
• imap-cleanup: delete preview json — Preview the same delete filter with JSON output
• imap-cleanup: delete folder dry run — Check the Old Projects folder before deletion
• imap-cleanup: delete folder dry run json — Check the same folder with JSON output
• imap-cleanup: delete folder recursive dry run — Check Old Projects and child folders before deletion

The delete preview and delete-folder entries are dry-run configurations and do not pass --execute.

License

MIT License.