gmail-cleaner_skill

Overview

This skill cleans and organizes Gmail accounts in bulk using the Gmail API. It authenticates with OAuth token files, scans mailbox patterns (top senders and categories), performs safe dry runs, and can trash or permanently delete messages, create labels, and set up filters across one or multiple accounts.

How this skill works

The tool uses Google OAuth credentials and token .pkl files to access Gmail via the API. It can scan a sample of messages to identify high-volume senders and categories, then apply batch operations (batchModify to move to Trash or batchDelete to permanently remove). It also creates labels and gmail.settings filters when authorized with the proper scopes, and can restore messages from Trash back to the inbox with labels applied.

When to use it

• Remove large volumes of promotional/newsletter emails quickly
• Bulk-delete messages from specific senders or matching search queries
• Set up labels and automated filters to keep incoming mail organized
• Run a deep cleanup routine to archive, mark read, and purge trash
• Restore important messages mistakenly trashed

Best practices

• Authenticate with a separate token file per account to manage multiple Gmail accounts safely
• Always run scans first to review top senders and category counts before deleting
• Use --dry-run to preview actions and confirm queries before permanent delete
• Re-authenticate with the settings scope (gmail.settings.basic) when filter creation fails with 403
• Prefer batchModify (trash) unless you explicitly need irreversible batchDelete; allow Gmail’s 30-day auto-purge when possible

Example use cases

• Clean a personal inbox by trashing all promotional messages older than 30 days
• Bulk-delete newsletters from specific senders across a work account before a migration
• Create a label set and filters to automatically route banking, social, and business mail
• Run a deep_clean to archive old mail, mark read, and clear promotions in one operation
• Restore missed transactional emails from Trash and apply an appropriate label