Gmail Auto-Cleanup

Free Google Apps Script that automatically deletes old notifications, promotions, and noise from your Gmail. Set up in 5 minutes, runs forever.

No extensions. No third-party access. No subscriptions.

The script runs 100% inside your Google account — your data never leaves your inbox.

Features

• Starter rule packs — Pre-built rules for Founders, Developers, and Marketers — just uncomment
• AI-powered setup — Use Claude to scan your inbox and generate personalized rules in seconds
• Dry run mode — Preview what will be deleted before enabling auto-cleanup
• HTML email reports — Styled daily summary with sample subject lines
• Telegram notifications — Optional instant alerts via your own Telegram bot
• Google Sheet log — Auto-created spreadsheet with full cleanup history
• 100% private — Runs in your own Google account, no external servers
• Daily autopilot — Runs every day at your preferred time with zero maintenance

Quick Start

Step 1. Install the script

1. Go to script.google.com → New project → Name it "Gmail Auto-Cleanup"
2. Delete everything in Code.gs and paste the contents of Code.gs from this repo
3. Click Save (Ctrl+S)

Step 2. Set up your rules

You have three options — pick one:

Option A: Let Claude scan your inbox (recommended)

The fastest way to get personalized rules. Open Claude and paste the prompt from claude-scan-prompt.md.

Claude will analyze your inbox patterns and generate a complete RULES array — just copy-paste it into Code.gs. Works best if you connect Gmail to Claude via MCP, but you can also describe your inbox manually.

Why this is great: Instead of guessing which senders to clean up, Claude reads your actual email history and finds the noise for you — newsletters you never open, notifications from tools you stopped using, expired promotions piling up.

Option B: Use a starter pack

The script includes pre-built rule packs in the RULES section:

Pack	For	Includes
Universal	Everyone	Google notifications, Promotions, Social, LinkedIn
Founder / CEO	Business owners	HubSpot, Notion, Slack, Zoom, Stripe, Calendly
Developer	Engineers	GitHub, GitLab, Vercel, Sentry, AWS, npm
Marketer	Marketing teams	Mailchimp, Semrush, Ahrefs, Google Ads, Meta Ads

Universal rules are active by default. To enable a starter pack, find it in Code.gs and remove the // comment marks from the rules you want.

Option C: Write your own rules

Add rules using Gmail search syntax:

{ query: 'from:noreply@example.com older_than:7d', label: 'Example' },

Step 3. Test with dry run

Select dryRun from the function dropdown → Click Run → Authorize when prompted.

You'll get an HTML email report showing exactly what would be deleted, with sample subject lines — without actually deleting anything. Review the report and adjust your rules if needed.

First run: Google will show an "This app isn't verified" warning. This is normal for personal scripts — click "Advanced" → "Go to Gmail Auto-Cleanup (unsafe)" to proceed. The script only accesses your own account and you can read every line of code.

Step 4. Enable daily cleanup

Select setupDailyTrigger → Click Run.

Done! Your inbox will be cleaned every morning at 6 AM (configurable). You'll get an email report after each cleanup.

Configuration

Edit the CONFIG object at the top of Code.gs:

const CONFIG = {
  // Schedule
  TRIGGER_HOUR: 6,              // When to run (24h format)
  ACTION: 'trash',              // 'trash' or 'archive'
  MAX_THREADS_PER_RULE: 100,    // Limit per rule (prevents timeout)

  // Email Reports
  SEND_EMAIL_REPORT: true,      // HTML report after cleanup
  REPORT_EMAIL: '',             // Leave empty = your Gmail address
  INCLUDE_SAMPLES: true,        // Show sample subjects in report
  SAMPLES_PER_RULE: 3,          // Number of samples per rule

  // Telegram (optional)
  SEND_TELEGRAM: false,         // Enable after bot setup
  TELEGRAM_BOT_TOKEN: '',       // From @BotFather
  TELEGRAM_CHAT_ID: '',         // Your chat ID

  // Google Sheet Log
  LOG_TO_SHEET: true,           // Log every cleanup to a spreadsheet
  SHEET_NAME: 'Gmail Cleanup Log'  // Auto-created in your Drive
};

Telegram Setup (optional)

1. Open Telegram, find @BotFather, send /newbot
2. Choose a name and username → copy the token
3. Send any message to your new bot
4. Open https://api.telegram.org/bot<TOKEN>/getUpdates → find your chat ID
5. Paste both into CONFIG → set SEND_TELEGRAM: true
6. Run testTelegram() to verify

Gmail Search Operators

Use these in your rules:

Operator	Example	Description
from:	from:noreply@github.com	From specific sender
subject:	subject:"weekly digest"	Subject contains phrase
older_than:	older_than:7d	Older than 7 days (d/m/y)
label:	label:Promotions	In specific label
is:unread	is:unread older_than:30d	Unread messages
has:attachment	has:attachment larger:10M	Has attachments
larger:	larger:5M	Larger than 5MB

Combine operators for precision: from:noreply@github.com subject:"CI" older_than:7d

Functions

Function	Description
dryRun()	Preview what would be deleted — sends HTML report, no changes made
cleanupGmail()	Run cleanup now (deletes/archives matching emails)
setupDailyTrigger()	Create daily trigger at configured hour
removeTrigger()	Stop auto-cleanup
testTelegram()	Send a test message to your Telegram bot

Safety

• Dry run first — Always run dryRun() before enabling auto-cleanup
• Trash, not delete — Emails go to Trash where they stay for 30 days. You can recover anything
• Archive option — Set ACTION: 'archive' to archive instead of trash
• Your code — You own it, you control it, you can read every line

Advanced: Deploy with clasp

If you manage multiple Google accounts or want version control:

npm install -g @google/clasp
clasp login
clasp create --title "Gmail Auto-Cleanup" --type standalone
clasp push

Then open the script in Apps Script editor, run setupDailyTrigger(), and authorize.

License

MIT License — free to use, modify, and distribute.

Credits

Built by O-CMO — Fractional CMO agency for B2B tech companies.