Skip to content

README.md

Latest commit

 

History

History
175 lines (120 loc) · 3.69 KB

README.md

File metadata and controls

175 lines (120 loc) · 3.69 KB
Raw

mailsweep is a terminal UI for finding the heaviest senders in your Gmail account and bulk-moving mail to Trash safely.

It is optimized for large inboxes:

  • incremental Gmail sync
  • local mailbox cache
  • lazy message drilldown loading
  • background sender prefetch
  • sortable and filterable sender leaderboard
  • safer bulk trash with age filters

What It Does

mailsweep scans your Gmail mailbox, groups messages by sender, and ranks senders by storage usage.

From the UI, you can:

  • see which senders take the most space
  • sort by total size, message count, or sender name
  • filter senders quickly
  • drill into a sender’s messages
  • select individual messages to move to Trash
  • bulk-move all messages from a sender to Trash
  • restrict bulk actions to messages older than 30, 90, 180, or 365 days

Messages are moved to Gmail Trash, not hard-deleted immediately.

Requirements

  • Go 1.25+
  • a Gmail account
  • a Google Cloud OAuth desktop client with Gmail API enabled

Setup

1. Create Google OAuth credentials

mailsweep expects credentials.json in one of these locations:

  • ~/.mailsweep/credentials.json
  • ./credentials.json

You can create it like this:

  1. Open https://console.cloud.google.com
  2. Create a Google Cloud project
  3. Enable the Gmail API
  4. Open APIs & Services -> OAuth consent screen
  5. Create an External app
  6. Add your Gmail address as a test user
  7. Open APIs & Services -> Credentials
  8. Create an OAuth client ID
  9. Choose Desktop app
  10. Download the JSON credentials file

Move it into place:

mkdir -p ~/.mailsweep
mv ~/Downloads/client_secret_*.json ~/.mailsweep/credentials.json

2. Run the app

go run .

Or build a binary first:

go build -o mailsweep .
./mailsweep

On first run, mailsweep opens a browser-based OAuth flow and stores your token locally in:

  • ~/.mailsweep/token.json

It also stores:

  • mailbox cache in ~/.mailsweep/cache.json
  • UI preferences in ~/.mailsweep/prefs.json

How To Use

Leaderboard

The first screen is the sender leaderboard.

It shows:

  • sender email
  • message count
  • total mailbox space used
  • a relative usage bar
  • age-preview counts once sender details are prefetched

Keys:

  • ↑↓ / j k: move selection
  • enter: open sender drilldown
  • D: bulk-move the selected sender’s mail to Trash
  • /: start filtering senders
  • s: cycle sort mode
  • r: refresh mailbox
  • q: quit

Sorting cycles through:

  • total size
  • message count
  • sender name

Filtering matches sender email or sender display text.

Drilldown

The drilldown screen shows messages for one sender.

Keys:

  • ↑↓ / j k: move selection
  • space: toggle a message
  • a: select all / clear all
  • d: move selected messages to Trash
  • esc: go back

Confirm Dialog

Before a trash action runs, mailsweep shows a confirmation step.

Keys:

  • y: confirm
  • n / esc: cancel
  • ←→ / h l: switch Yes/No
  • [ / ]: change the age filter

Age filter options:

  • all messages
  • older than 30 days
  • older than 90 days
  • older than 180 days
  • older than 365 days

Performance Notes

The app avoids expensive rescans where possible:

  • refresh uses Gmail history-based incremental sync when available
  • sender message bodies are not fetched during the initial scan
  • drilldown data is loaded only when needed
  • selected/nearby senders are prefetched in the background
  • prefetch cache is bounded in memory

Development

Format and build:

gofmt -w .
go build ./...

Safety Notes

  • mailsweep uses Gmail modify scope
  • bulk actions move messages to TRASH
  • messages may remain recoverable through Gmail Trash depending on Gmail retention behavior

License

See LICENSE.