✉️ Email Operations — Bounce Handler Demo

• Hard/soft/unknown classification — Categorizes bounces by SMTP response codes
• SMTP code matching — Recognizes 550, 421, and dozens of enhanced status codes
• Regex pattern matching — Catches bounces from non-standard error messages
• Raw .eml parsing — Extract bounce info directly from bounce notification emails
• List cleaning — Removes hard-bounced addresses from your mailing list
• JSON/CSV output — Export categorized bounces for further processing

# Categorize bounces from a JSON file
python src/bounce_handler.py --input examples/sample_bounces.json

# Parse a raw bounce email (.eml)
python src/bounce_handler.py --parse-raw bounce_notification.eml

# Clean a mailing list by removing hard bounces
python src/bounce_handler.py --input bounces.json --clean emails.txt --output clean.txt


python src/bounce_handler.py --input bounces.json --clean my_list.txt --output cleaned_list.txt

[
  {
    "email": "user@example.com",
    "smtp_code": "550",
    "diagnostic": "5.1.1 The email account does not exist",
    "timestamp": "2026-03-14T12:00:00Z"
  },
  {
    "email": "other@example.com",
    "smtp_code": "421",
    "diagnostic": "Try again later",
    "timestamp": "2026-03-14T12:01:00Z"
  }
]