📧 Gmail Bounce Cleaner Pro

A powerful Python-based tool to clean, validate, and update email leads by intelligently analyzing Gmail bounce messages, auto-replies, and account updates.

---

🚀 Introduction

Gmail Bounce Cleaner Pro is an advanced email cleaning system designed for businesses, marketers, and automation workflows.

It connects to Gmail accounts, scans recent emails, and intelligently:

• Detects bounced emails
• Identifies out-of-office replies (and ignores them)
• Updates contacts who changed email
• Replaces leads who left companies
• Generates a clean, ready-to-use dataset

This tool ensures high-quality email lists and protects your sender reputation.

---

⚙️ How It Works

1. Connects to Gmail accounts via IMAP
2. Reads latest emails from Inbox and Spam
3. Detects:
   • System bounce messages (DSN)
   • Non-system replies (OOO, updates, etc.)
4. Extracts only real failed recipients (no false positives)
5. Classifies each case:
   • Bounced
   • Updated (Left Company)
   • Updated (Self Email Change)
   • Out of Office (ignored)
6. Saves:
   • Highlighted results
   • Cleaned dataset
7. Supports resume if interrupted

---

✨ Features

• 📬 Multi Gmail account support
• 🧠 Smart bounce detection (no false positives)
• 🚫 Ignores Out-of-Office replies
• 🔄 Detects email changes automatically
• 🧍 Detects "left company" + assigns new contact
• 📊 Live progress tracking
• 💾 Resume functionality (checkpoint system)
• 📁 Excel-based input & output
• ⚡ Real-time saving (no data loss)
• 🛑 Safe interruption (Ctrl+C supported)

---

📦 Technologies Used

• Python → Core language
• imaplib → Gmail connection
• email → Email parsing
• pandas → Excel handling
• re (Regex) → Pattern detection
• json → State management
• openpyxl → Excel writing
• socket & time → Stability & retries

---

🔑 Input Files

1. credentials.json

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

2. input_emails.xlsx

Required column:

Email

🛠 Installation

1. Clone Repository

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

2. Install Dependencies

pip install pandas openpyxl

▶️ Usage

Run the script:

python BounceCleanerPro.py

📊 Output Files

📌 Bounced_Highlighted.xlsx

Contains ONLY:

• Bounced
• Updated (Left Company)
• Updated (Self Email Change)

📌 Cleaned_Data.xlsx

Final cleaned dataset:

• Removed bounced emails
• Updated email addresses
• Updated names (if available)

📌 pending_scan.json

• Stores progress
• Allows resume if interrupted

📌 Classification Logic

🔴 Bounced

• Invalid email
• Delivery failed
• Rejected messages

🔄 Updated (Self Email Change)

• User changed their email Name remains same

🧍 Updated (Left Company)

• Person left organization
• New valid contact found
  Must include:
• Email
• First + Last Name

🟡 Out of Office

• Ignored
• Not stored in output

🎯 Benefits

• Clean your email lists automatically
• Reduce bounce rates
• Improve email deliverability
• Protect Gmail accounts from limits
• Save hours of manual work
• Increase campaign success rate

⚡ Performance Tips

• Use multiple Gmail accounts
• Keep inbox clean
• Avoid scanning too many emails at once
• Close Excel files while running script

⚠️ Limitations

• Works only with Gmail (IMAP)
• Requires App Passwords
• Depends on email formats
• Not real-time (batch processing)

🔒 Security Notes

• Never upload credentials.json
• Always use Gmail App Passwords
• Keep your data private
• Do not expose sensitive email lists

💼 Use Cases

• Lead generation cleaning
• Cold email campaigns
• Marketing automation
• CRM data cleaning
• Email deliverability optimization

👨‍💻 Author

Malki Aman

⭐ Support

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

📜 Disclaimer

This tool is intended for ethical use only. Users are responsible for complying with email policies and laws.