📧 BatchBounce Analyzer

A powerful Python-based tool to detect fully blocked email batches by analyzing Gmail bounce (DSN) messages.

---

🚀 Introduction

BatchBounce Analyzer is designed for developers, marketers, and automation systems that rely on bulk email sending.

It connects to multiple Gmail accounts and analyzes recent bounce (DSN) emails to identify:

• Fully blocked email batches
• Affected recipients
• Problematic sending accounts

This helps you quickly detect deliverability issues and take action before damaging your sender reputation.

---

⚙️ How It Works

1. Connects to Gmail using IMAP
2. Scans the last 50 bounce (DSN) emails from:
   • Inbox
   • Spam (optional)
3. Extracts:
   • Failed recipients
   • Original message IDs (to group batches)
4. Groups failures into batches
5. Detects fully blocked batches (≥ 10 recipients)
6. Generates a CSV report
7. Prints a detailed summary

---

✨ Features

• 📬 Multi Gmail account support
• 🔍 Smart DSN/bounce detection
• 📊 Full batch block identification
• 🧠 Advanced recipient extraction (headers + body)
• ⚡ Fast processing (limited scan scope)
• 🔁 Retry mechanism for network errors
• 📁 CSV export for analysis
• 👁 Preserves unread/read email status
• 🗂 Optional Spam folder scanning

---

📦 Libraries Used

This project uses only built-in Python libraries:

• imaplib
• email
• re
• json
• csv
• os
• time
• socket
• html

No external dependencies required.

---

🔑 Credentials Setup

Create a file named credentials.json:

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

Important:

Use Gmail App Password, not your actual password Enable 2FA before generating app password

🛠 Installation

1. Clone Repository

git clone https://github.com/yourusername/BatchBounce-Analyzer.git
cd BatchBounce-Analyzer

2. Install Python

Ensure Python 3.8 or higher is installed:

python --version

3. No Dependencies Needed

• All required libraries are built-in.

▶️ Usage

Run the script:

python BatchBounce-Analyzer.py

📊 Output

📁 CSV Report

File generated:

full_batch_blocks_report.csv

🖥 Terminal Output

• Number of blocked batches per account
• List of affected Gmail accounts
• Unique failed recipients

📌 Key Concepts

🔹 DSN (Delivery Status Notification)

• Automatic bounce messages sent by mail servers when delivery fails.

🔹 Full Batch Block

• A batch is considered fully blocked when:

10 or more recipients fail (default setting)

⚙️ Configuration

You can modify these values inside the script:

BATCH_SIZE = 10
LAST_N_MESSAGES = 50
SCAN_SPAM = True
MAX_ACCOUNT_RETRIES = 3
RETRY_DELAY_SECONDS = 5

💡 Use Cases

• Email marketing systems
• Cold email automation tools
• Lead generation pipelines
• Deliverability monitoring systems
• Gmail account health tracking

⚠️ Limitations

• Works only with Gmail (IMAP)
• Requires App Password authentication
• Not real-time (batch analysis only)
• Accuracy depends on DSN formats

🔒 Security Notes

• Never share your credentials.json file
• Do not upload credentials to GitHub
• Always use App Passwords
• Consider encrypting credentials for production

👨‍💻 Author

Malki Aman

📬 Contact

For business inquiries or custom solutions:

• GitHub: malkiaman-dev
• Email: your-email

⭐ Support

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

⚠️ Disclaimer

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