flufl.bounce is a Python library designed for robust detection and parsing of email bounce messages. It helps identify undeliverable emails, extract recipient information, and understand the reason for delivery failures. The current major version is 4.0, released in August 2023, and it receives updates as needed, typically for Python compatibility or bug fixes.
Install & Compatibility
Where this runs
tested against v5.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
from flufl.bounce import Bounce
This quickstart demonstrates how to parse a raw bounce email string into an `email.message.Message` object, then use `flufl.bounce.Bounce` to detect if it's a bounce and extract key information like bounce type, failed recipients, and diagnostic codes. Remember to always pass an `email.message.Message` object to the `Bounce` constructor.
from email import message_from_string
from flufl.bounce import Bounce
# Simulate a bounce email content
bounce_email_content = """
From: MAILER-DAEMON@example.com
To: original_sender@example.com
Subject: Undelivered Mail Returned to Sender
This is the mail system at host example.com.
I'm sorry to have to inform you that your message could not be delivered to one or more recipients.
It's attached below.
<nonexistent@example.com>: host mail.example.com[192.0.2.1] said: 550 5.1.1
<nonexistent@example.com>: Recipient address rejected: User unknown
"""
# Parse the raw email string into an email.message.Message object
msg = message_from_string(bounce_email_content)
# Create a Bounce object from the parsed message
bounce = Bounce(msg)
print(f"Is this a bounce message? {bounce.is_bounce}")
if bounce.is_bounce:
print(f"Bounce type: {bounce.type}")
print(f"Failed recipients: {bounce.recipients}")
print(f"Diagnostic code: {bounce.diagnostic_code}")
else:
print("Not recognized as a bounce by flufl.bounce.")
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.