Open-source self-hosted tool to bulk-trash Gmail messages with a friendly filter builder for Gmail's search operators — combine unread-only, larger than N MB, older than N days, has List-Unsubscribe, category, and raw queries without memorizing syntax, preview matches with per-message sizes, select every match in one click, and trash tens of thousands in seconds. Built with TanStack Start + React + Tailwind.
- Safe: moves messages to Gmail Trash (recoverable for 30 days). Never
permanent-deletes — uses only the
gmail.modifyscope. - Private: OAuth tokens live in your browser's
localStorage. The server only proxies Gmail API calls and the OAuth code exchange (which requires the client secret). - Truly bulk: "Select all matching" grabs every message matching your
filters (up to 50,000) in one click — no page-by-page checkbox rounds —
and trashing uses Gmail's
messages.batchModify(up to 1000 ids per call), so clearing thousands of emails takes seconds.
- Go to https://console.cloud.google.com/ → new project.
- APIs & Services → Library → enable Gmail API.
- OAuth consent screen → External → fill app info → add scope
https://www.googleapis.com/auth/gmail.modify→ add yourself as a test user. (Testing mode is fine for personal use.) - Credentials → Create credentials → OAuth client ID → Web application.
- Authorized redirect URIs — add one per host you'll run on:
http://localhost:5173/api/auth/google/callbackhttps://your-deployment.example.com/api/auth/google/callback
- Copy the Client ID and Client secret.
Set these as environment variables (or via your hosting provider's secret manager):
GOOGLE_CLIENT_ID=...apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...
bun install
bun run dev
Open http://localhost:5173, click Connect Gmail, authorize, then filter and trash away.
| UI field | Gmail query operator |
|---|---|
| From contains | from: |
| To | to: |
| Subject contains | subject: |
| Body / keyword | free text |
| Unread only | is:unread |
| Has / no attachment | has:attachment / -has:attachment |
| Category | category:promotions etc. |
| Label | label: |
| Older / newer than (days) | older_than:Nd / newer_than:Nd |
| Larger / smaller than (MB) | larger:NM / smaller:NM |
| Mailing list | list:* (has List-Unsubscribe header) |
| Raw | anything from https://support.google.com/mail/answer/7190 |
Trashed messages are excluded automatically (-in:trash).
MIT.