Repository navigation
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