📧 Email Deliverability Audit & Self-Cleaning System

A safe, automated way to improve email deliverability without deleting real users, subscribers, or compliance-relevant records.

---

🧩 Problem Statement

• Over time, systems accumulate bounced, invalid, and spam-reported email addresses.
• Blind deletion is risky because some emails belong to real users or subscribers, while not cleaning them hurts sender reputation and email deliverability.
• Manual cleanup does not scale and is error-prone.

---

🎯 What This Project Does

This project introduces a rule-based email audit system that:

• Separates email behaviour from user identity
• Preserves all user accounts by default
• Identifies only high-confidence junk for cleanup
• Improves email deliverability automatically
• Can run every 30–60 days with zero manual effort

---

🧠 Core Principle

We do not delete people. We control communication first and archive only clearly dead records.

---

📥 Video Explainer

---

📥 Input Data

The script consumes CSV exports from SendGrid and internal systems:

• suppression_blocks.csv
• suppression_bounces.csv
• suppression_invalid_emails.csv
• suppression_spam_reports.csv

All files are read in read-only mode from a single directory.

---

🧺 Bucket Classification (A–E)

Bucket	Meaning
A	Active users with email delivery issues
B	Spam reporters
C	Never logged in + hard bounce
D	Obvious junk / test emails
E	Temporary delivery issues

---

🧾 Action Policy (Final)

• Bucket A: Stop bulk emails, allow transactional only
• Bucket B: Block all emails permanently, keep account
• Bucket C: Mark inactive, stop emails, reactivate only after login + valid email
• Bucket D: Safe to archive or soft delete (only cleanup bucket)
• Bucket E: Pause emails for 30–60 days and retry later

---

🧪 Output

• Human-readable HTML audit report
• Bucket-wise counts and explanations
• Clear Safe Cleanup Summary (Bucket D only)
• Full audit table with color-coded headers

---

🔁 Automation

Designed to run as a cron job:

• Frequency: every 30 or 60 days
• Fully self-cleaning over time
• No manual intervention needed

Example:

0 2 1 * * python email_deliverability_report.py

Run email_deliverability_report.py at 2:00 AM on the 1st day of every month.

- 0 → minute (0th minute)
- 2 → hour (2 AM)
- 1 → day of month (1st)
- * → every month
- * → every day of the week

---

🏗 Flow

# 🔄 Email Deliverability Audit – Flow Diagram

```text
┌────────────────────────────┐
│        Cron / Manual       │
│   Script Execution Start   │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────┐
│        Load CSV Files      │
│  (SendGrid + Internal)     │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────┐
│     Normalize Email Data   │
│ (lowercase, deduplicate)  │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────┐
│ Assign Suppression Type    │
│ block / bounce / invalid  │
│ spam                       │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────┐
│  Enrich with User Context  │
│ login flag, last login     │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────┐
│     Bucket Classification  │
│        (A – E)             │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────────────────┐
│ Decision Logic                          │
│ cleanup_candidate$ + recommended_action│
└─────────────┬──────────────────────────┘
              │
              ▼
┌────────────────────────────┐
│  Safe Cleanup Count        │
│     (Bucket D only)        │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────┐
│ Generate HTML Audit Report │
│ Buckets + Table + Summary │
└─────────────┬──────────────┘
              │
              ▼
┌────────────────────────────┐
│   Auto-open in Browser     │
└────────────────────────────┘

---

⚙️ Requirements & Run

python -m pip install pandas
python email_deliverability_report.py

The HTML report opens automatically in the browser.

---

📩 Contact

Name	Details
👨‍💻 Developer	Sachin Arora
📧 Email	sachnaror@gmail.com
📍 Location	Noida, India
📂 GitHub	https://github.com/sachinaror
🌐 Website	https://about.me/sachin-arora
📱 Phone	+91 9560330483

Happy coding! 🎯🔥

---

End Result