Releases: smcneece/gmail-cleanup-script
Releases · smcneece/gmail-cleanup-script
v2025.08.3 - Simplified & Optimized
Release Date: August 23, 2025
Type: Major Cleanup & Performance Release
🧠 Core Intelligence
Back to Basics - KISS Principle Applied
- Simplified targeting: Removed complex starred/important/age filtering - now just deletes oldest emails first
- Mathematical precision maintained: Still calculates exact number of emails to delete based on storage targets
- Performance optimized: Storage checks reduced from every 200 to every 400 emails (50% fewer API calls)
- Clean architecture: Removed bloated features that overcomplicated the original simple goal
Enhanced Efficiency
- Faster execution: Fewer mid-cleanup storage checks without sacrificing safety
- Cleaner code: Removed unused variables and complex filtering logic
- Better reliability: Fixed broken report function that referenced undefined variables
- Gmail API accuracy: Real size sampling maintained for precise calculations
🚀 Major Features
Simplified Configuration
- Single target setting: Just set
TARGET_FOLDER- script handles the rest - No complex queries: Removed starred/important exclusions and age restrictions
- Back to core purpose: Delete oldest emails from target folder when storage exceeds threshold
- Production-ready defaults: Safe settings work out of the box with DRY_RUN mode
Fixed Reporting System
- Corrected daily reports: Removed references to undefined MIN_AGE_DAYS and EMERGENCY_THRESHOLD
- Accurate configuration display: Reports now show actual settings being used
- Cleaner report format: Streamlined information without confusing complexity
🎯 Perfect For
Security Camera Systems
- Blue Iris users: Simple, reliable cleanup of motion alert emails
- Home Assistant: Manages notification buildup without complex filtering
- Any camera system: Handles high-volume automated emails efficiently
- Set-and-forget: No need to configure complex rules or exclusions
Gmail Storage Management
- Free Gmail users: Keeps your 15GB functional for camera/IoT systems
- Automated email systems: Perfect for systems that send regular status emails
- Simple needs: When you just want old emails deleted, not complex preservation rules
📋 Technical Specifications
Requirements
- Google account with Gmail
- Google Apps Script (free)
- Advanced Drive API enabled
- Advanced Gmail API enabled
Performance
- Reduced API calls: Storage monitoring every 400 emails vs. every 200
- Maintained accuracy: Still uses mathematical approach with real Gmail API sizes
- Faster execution: Fewer mid-process checks while maintaining safety
- Cleaner logs: Simplified output without complex filtering information
Compatibility
- All Gmail accounts: Works with free and paid Google accounts
- All camera systems: Blue Iris, Frigate, Home Assistant, generic SMTP
- Simple targeting: Works with sent, trash, inbox, labels, or custom searches
🛠️ Installation
Quick 5-minute setup:
- Open [script.google.com](https://script.google.com) and create new project
- Enable APIs: Drive API + Gmail API in Services
- Copy script from
gmail_cleanup_script.js - Test safely with built-in DRY_RUN mode
- Configure simple settings: Just TARGET_FOLDER and STORAGE_THRESHOLD
Complete setup guide with screenshots in README.md
This release gets back to the core mission: simple, mathematical Gmail cleanup without unnecessary complexity!
v2025.08.3 - Performance & Precision Upgrade
Release Date: August 23, 2025
Type: Major Performance Enhancement
🧠 Core Intelligence
4x Performance Boost with Enhanced Precision
- Optimized batch processing: 200-email batches (vs 100) with 500ms delays (vs 1000ms)
- Real-time storage monitoring: Checks storage every 200 deletions to prevent over-deletion
- Execution time: 2 minutes 38 seconds vs previous 6+ minute timeouts
- Proven results: Deleted 580 emails (308MB) with pinpoint accuracy
Enhanced Size Calculations
- Real Gmail API sizes: Uses
sizeEstimateinstead of fake 50KB estimates - Smart sampling: Analyzes 200 emails for accurate average calculations
- Improved fallbacks: 100KB base + 50KB per message when API unavailable
- Mathematical precision maintained: Still calculates exact deletion needs
🛡️ Safety & Testing
Production-Ready Safety Features
- DRY_RUN mode: Test safely without actual deletion (enabled by default)
- Safety locks: LockService prevents overlapping cleanup runs
- Hard caps: MAX_DELETE_PER_RUN prevents accidental mass deletion
- Age-aware targeting: Prefers older emails while ensuring cleanup success
- Emergency override: Critical storage levels (90%+) bypass age restrictions
- Conservative targeting: Automatically excludes starred and important emails
Enhanced Error Handling
- No hardcoded fallbacks: Script aborts safely if storage undetectable
- Email notifications: Alerts sent when cleanup encounters problems
- Comprehensive logging: Detailed execution information for troubleshooting
🎯 Perfect For
Security Camera Systems
- Blue Iris users: Automatically manages motion alert email overflow
- Frigate integration: Keeps Gmail pipeline clear for detection notifications
- NVR systems: Handles high-volume automated email alerts
- Evidence preservation: Minimal deletion maintains maximum forensic data
Home Automation Enthusiasts
- Home Assistant: Manages notification email buildup automatically
- IoT integrations: Handles sensor alerts and status emails
- Smart home monitoring: Keeps Gmail functional for critical notifications
- Android users: Manages Google account storage across all services
🔧 User Experience Improvements
Simplified Configuration
- Single variable targeting: Only edit
TARGET_FOLDER, script auto-builds safe queries - Production-ready defaults: Safe settings work out of the box
- Flexible targeting: Easy configuration for sent, trash, labels, or custom queries
- Visual setup guide: Step-by-step screenshots for Google's security warnings
Enhanced Documentation
- AI audit integration: Users can verify code safety with any AI assistant
- Complete visual walkthrough: Images for every permission step
- TARGET_FOLDER examples: Clear configuration options for different use cases
- Performance metrics: Real test results with timing and accuracy data
📋 Technical Specifications
Requirements
- Google account with Gmail
- Google Apps Script (free)
- Advanced Drive API enabled
- Advanced Gmail API enabled
Performance
- Speed: 4x faster than previous version
- Accuracy: 90%+ size prediction accuracy
- Execution time: Under 3 minutes for typical cleanup
- API efficiency: Optimized batch sizes and delays
- Memory usage: Efficient processing with real-time monitoring
Compatibility
- All Gmail accounts: Free (15GB) through enterprise (unlimited)
- All camera systems: Blue Iris, Frigate, generic SMTP alerts
- All platforms: Works entirely in Google's cloud infrastructure
- No dependencies: Self-contained Google Apps Script
🛠️ Installation
Complete setup takes 5 minutes:
- Open script.google.com and create new project
- Enable APIs: Drive API + Gmail API in Services
- Copy script from
gmail_cleanup_script.js - Test safely with built-in DRY_RUN mode
- Set up triggers for hourly cleanup + daily reports
Full visual guide with screenshots available in README.md
v2025.08.2 - Mathematical Gmail Storage Management
Release Date: August 22, 2025
Type: Initial release
🧠 Core Intelligence
Mathematical Precision Cleanup
- Calculates exact number of emails to delete based on storage targets
- 99.7% accuracy tested (predicted 742MB freed, actual 740MB freed)
- Smart email counting across all Gmail folders (inbox, sent, trash, spam)
- Average email size calculation for precise targeting
- One intelligent run vs 340+ guessing attempts (85+ hours saved)
Advanced Storage Monitoring
- Drive API integration for accurate total storage across Gmail + Drive + Photos
- Real-time storage percentage tracking
- Configurable storage thresholds (default: 75% triggers cleanup)
- Conservative cleanup targeting (deletes to 73% for safety buffer)
🚀 Major Features
Intelligent Automation
- Hourly monitoring with smart cleanup calculations
- Only runs when storage exceeds threshold - no unnecessary processing
- Batch processing with Gmail API rate limiting (100 emails per batch)
- Automatic target folder selection (sent items, trash, inbox, custom labels)
- Evidence preservation mode for security/forensic use cases
Professional Reporting
- Daily email reports with detailed storage statistics
- Cleanup activity summaries with exact numbers deleted
- Email folder breakdowns (inbox, sent, trash counts)
- Error notifications with detailed logs
- Complete audit trail of all deletion activity
Smart Configuration
- Zero-configuration operation after initial setup
- Configurable email addresses for reports
- Multiple target folder options (
in:sent,in:trash,label:custom) - Comprehensive safety features and error handling
- Professional setup documentation with visual guides
🎯 Perfect For
Security Camera Systems
- Blue Iris motion alerts and recording notifications
- Frigate detection alerts
- NVR system status emails
- Evidence retention with minimal cleanup
Home Assistant Integration
- Automated notification cleanup
- System status email management
- Sensor alert email handling
- Android backup account maintenance
Business Applications
- High-volume Gmail accounts
- Automated system status emails
- Data retention compliance
- Storage cost optimization
📋 Technical Specifications
Requirements
- Google account with Gmail (free tier supported)
- Google Apps Script access (free)
- Drive API and Gmail API enabled
Supported Integrations
home-assistantblue-irisfrigatenvrsecurity-camerasandroidbackupautomationgoogle-apps-script
Performance
- Processing speed: ~280 emails deleted per minute
- API efficiency: Respects Gmail quotas and rate limits
- Storage accuracy: Mathematical precision vs guesswork
- Error handling: Comprehensive with email notifications
🛠️ Installation
- Copy script to Google Apps Script
- Enable Drive API and Gmail API services
- Configure email addresses in script
- Set up hourly cleanup trigger
- Set up daily report trigger
- Done - fully automated operation
Complete setup guide with screenshots included in documentation.