Gmail Cleanup
github.com
- Free plan
- Web
What Gmail Cleanup is
Gmail Cleanup is a free, open-source Google Apps Script for clearing older promotions, newsletters and marketing messages from Gmail. By default, it unsubscribes from promotions and newsletters older than one day, moves them to Trash and also trashes spam. Trash remains recoverable for 30 days. Detection uses Gmail’s Promotions category, newsletter subject and label patterns, and sender patterns such as noreply and marketing. The script reads List-Unsubscribe headers and supports RFC 8058 HTTP and mailto methods. Senders can be excluded from cleanup or unsubscribing while their messages remain, with lists editable in the script or Google Sheet. Setup uses Google Apps Script, the Gmail API, Sheets and Drive. Dry-run mode previews actions, while a Sheet records unsubscribe attempts and skipped senders. Optional triggers run cleanup daily and unsubscribe passes every three days. Sender-pattern searches may catch legitimate transactional mail.
Who it suits
It suits Gmail users who want scripted cleanup and unsubscribe handling with logs and editable exclusions. Users managing important transactional mail should review previews and exclusions first.
Good to know, and what to watch
- Free, open-source Gmail automation
- Unsubscribe support for HTTP and mailto
- Dry-run previews cleanup actions
- Editable sender exclusion lists
- 30-day Trash recovery
- Gmail-only support
- Sender patterns may catch legitimate mail
- Requires Google Apps Script and API setup
The verdict
Gmail Cleanup combines unsubscribe handling with reversible Trash-based cleanup and logging. Its setup requirements and possible sender-pattern matches make dry-run review and exclusions important.
What the maker publishes
- Automation
- Optional time-based triggers can run daily cleanup and an unsubscribe pass every three days. source
- Automation
- Optional time-based triggers can run cleanup daily and unsubscribe every three days. source
- Cleanup
- By default, it unsubscribes from and moves promotions and newsletters older than one day to Trash, and moves spam to Trash. source
- Default actions
- By default, it unsubscribes and moves promotions and newsletters older than one day to Trash, and moves spam to Trash. source
- Detection
- It targets Gmail's Promotions category, newsletter subject and label patterns, and sender patterns such as noreply and marketing. source
- Detection
- It targets Gmail's Promotions category, newsletter subject or label patterns, and sender patterns such as noreply and marketing. source
- Integration
- Setup instructions require creating a project in Google Apps Script and enabling the Gmail API; the script also uses Google Sheets and Drive. source
- Integrations
- Setup uses Google Apps Script, the Gmail API, and a Google Sheet created in Google Drive for logs and editable sender lists. source
- License
- The repository lists the project under the MIT license. source
- License
- The repository is distributed under the MIT license. source
- Limit
- The README warns that sender-pattern searches may match legitimate transactional messages and recommends excluding domains and running dryRun first. source
- Logging
- The script creates a Google Sheet that records unsubscribe attempts and skipped senders, and provides editable excluded-sender and unsubscribe-only lists. source
- Notable limit
- The README cautions that sender-pattern searches can match legitimate transactional email and recommends whitelisting domains and running dryRun first. source
- Preview
- A dry-run mode previews what would be deleted before cleanup runs. source
- Preview and logging
- Dry-run mode previews actions, and unsubscribe attempts are logged in a Google Sheet. source
- Protection
- Keyword checks in Spanish and English protect certain health, government, immigration, legal, education, and transactional emails for ambiguous queries. source
- Protection
- Keyword detection in English and Spanish is used to protect potentially important health, government, immigration, legal, education, and transactional emails in ambiguous searches. source
- Purpose
- Gmail Cleanup is a Google Apps Script that cleans Gmail by removing old promotions, newsletters, and marketing emails, and unsubscribing before deletion. source
- Purpose
- Gmail Cleanup is a Google Apps Script for automated Gmail inbox cleanup and mass unsubscribe. source
- Recoverability
- The README says Trash items remain recoverable for 30 days and are not permanently deleted by default. source
- Recoverability
- The README says messages moved to Trash are recoverable for 30 days and permanent deletion is off by default. source
- Sender controls
- Users can exclude senders from cleanup or unsubscribe while keeping their emails, with lists editable in the script or Google Sheet. source
- Sender controls
- Users can exclude senders from cleanup or unsubscribe from them while keeping their emails, using script settings or Google Sheet tabs. source
- Unsubscribe
- It parses List-Unsubscribe headers and supports RFC 8058 one-click HTTP and mailto endpoints. source
Checked against the maker's pages on 11 Oct 2026.