Privacy-first, self-hosted Gmail cleanup. Runs locally on your machine — no cloud backend, no analytics.

Scan Spam, Trash, and Inbox, group messages by sender, and bulk delete, block, keep (whitelist), or mass unsubscribe.

Repository: github.com/Kava4/mail-cleaner

Double-click run.bat in the project root:

• Checks Node.js
• Runs npm install if needed
• Warns if data/credentials.json is missing
• Opens the browser and starts npm run dev

git clone https://github.com/Kava4/mail-cleaner.git
cd mail-cleaner
npm install
npm run dev

Open http://localhost:3000 and click Connect Gmail.

1. Open Google Cloud Console
2. Select a project → New Project (e.g. mail-cleaner)

1. APIs & Services → Library
2. Search Gmail API → Enable

1. APIs & Services → OAuth consent screen
2. User type: External (personal Gmail) or Internal (Google Workspace)
3. Fill in app name and support email
4. Scopes: the app requests these automatically on sign-in:
   • https://mail.google.com/ (read, modify, permanent delete)
   • https://www.googleapis.com/auth/gmail.settings.basic (block filters)
5. Test users: add your Gmail address (required while the app is in Testing)

1. APIs & Services → Credentials → Create Credentials → OAuth client ID
2. Application type: Web application
3. Authorized redirect URIs:

   http://localhost:3000/api/auth/callback
   

4. Download JSON and save as:

mail-cleaner/data/credentials.json

Never commit credentials.json to GitHub. It is listed in .gitignore.

1. Run the app and click Connect Gmail
2. Grant permissions (full Gmail access is required for permanent delete from Trash/Spam)
3. Click Scan mailboxes

mail-cleaner/
├── apps/web/              Next.js UI + API routes
├── packages/shared/       Shared types & spam rules
├── data/                  ← not committed to Git
│   ├── credentials.json   OAuth client (you provide this)
│   ├── token.json         Access/refresh token (created on sign-in)
│   └── whitelist.json     Senders you marked as Keep
└── README.md

Tips

• Filter by Type → Newsletter, then Unsub all visible, then Delete selected
• If delete fails: Sign out → delete data/token.json → Connect again

npm run build
npm run start

Default port: 3000. For another port: PORT=3001 npm run start

Copy .env.example to apps/web/.env.local and adjust if needed.

Self-hosted: each user runs their own instance. You share code only, never credentials or tokens.

Not supported out of the box: Vercel/Netlify serverless (tokens stored on local filesystem in data/).

• 100% local — tokens in data/token.json
• No third-party analytics
• Revoke access anytime: Google Account → Third-party apps

MIT