Features

This chapter covers the core features and capabilities of Bounce Handler.

Features

• 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
• Diagnostic extraction — Pulls the human-readable error message from each bounce

Requirements

• Python 3.10+
• No external dependencies (stdlib only)

Quick Start

Follow this guide to get Bounce Handler up and running in your environment.

Quick Start

# 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

Input Format

The tool expects a JSON array of bounce records:

[
  {
    "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"
  }
]