🧹 Gmail Read Cleaner Pro

A powerful Python-based tool to automatically clean Gmail accounts by moving ONLY read emails from Inbox and Spam to Trash.

---

🚀 Introduction

Gmail Read Cleaner Pro is designed to help users keep their Gmail accounts clean and organized.

It connects to multiple Gmail accounts and safely removes clutter by:

• Moving only read emails to Trash
• Keeping all unread emails untouched
• Supporting multiple accounts
• Allowing resume if interrupted

Perfect for users who receive large volumes of emails daily.

---

⚙️ How It Works

1. Loads Gmail accounts from credentials.json
2. Connects using IMAP (secure login)
3. Scans:
   • Inbox
   • Spam folder
4. Finds ONLY emails marked as READ (SEEN)
5. Moves them to Trash (not permanently deleted)
6. Saves progress to resume later

---

✨ Features

• 📬 Multi Gmail account support
• 🧹 Cleans Inbox and Spam folders
• 👁 Keeps unread emails safe
• 🔄 Resume functionality (state tracking)
• ⚡ Batch processing for speed
• 🛑 Safe interruption handling
• 🧪 Dry-run mode (simulation)
• 🔒 Secure login using App Passwords
• 📉 Minimal console output

---

📦 Technologies Used

• Python → Core language
• imaplib → Gmail IMAP connection
• json → Credentials & state storage
• os & sys → File handling
• socket → Network handling
• typing → Type hints

---

🔑 Credentials Setup

Create a credentials.json file:

[
  {
    "email": "your_email@gmail.com",
    "app_password": "your_app_password"
  }
]

Important:

Use Gmail App Passwords Do NOT use your real Gmail password

Installation

1. Clone Repository

git clone https://github.com/yourusername/Gmail-Read-Cleaner-Pro.git
cd Gmail-Read-Cleaner-Pro

2. Install Python

Ensure Python 3.8+ is installed:

python --version

3. No Dependencies Required

Uses only built-in Python libraries.

▶️ Usage

Run the script:

python main.py

⚙️ Configuration

Inside the script:

DRY_RUN = False

Modes:

• True → Simulation only (no deletion)
• False → Actually moves emails to Trash

📊 How Resume Works

The tool creates:

• gmail_cleaner_state.json

This file stores:

• Last processed email UID
• Progress per account

So if interrupted, it resumes from where it stopped.

🔒 Safety Features

• Never deletes unread emails
• Does not permanently delete emails
• Moves emails to Trash only
• Supports dry-run testing
• Handles errors safely

⚡ Performance Tips

• Run in batches (default optimized)
• Use stable internet connection
• Keep Gmail IMAP enabled
• Avoid running multiple cleaners at once

💡 Use Cases

• Clean cluttered Gmail inbox
• Manage multiple email accounts
• Maintain productivity
• Reduce inbox overload
• Prepare accounts for automation

⚠️ Limitations

• Works only with Gmail
• Requires App Password
• Depends on IMAP access
• Cannot recover permanently deleted emails

🔐 Security Notes

• Never upload credentials.json to GitHub
• Use App Passwords only
• Keep your accounts secure
• Enable 2FA on Gmail

👨‍💻 Author

Malki Aman

⭐ Support

If you find this project useful, give it a star ⭐

📜 Disclaimer

This tool is intended for personal and professional email management. Users are responsible for their data and Gmail usage policies.