flufl.bounce: Email Bounce Detectors

4.0 · active · verified Thu Apr 16

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.

Common errors

```
TypeError: Bounce() got an unexpected keyword argument 'message_string'
```
cause Attempting to initialize Bounce with a deprecated `message_string` keyword argument.

fix The `Bounce` constructor no longer accepts `message_string`. Convert your raw email content into an `email.message.Message` object first: `msg = message_from_string(your_email_string); bounce = Bounce(msg)`.
```
TypeError: Bounce() takes 1 positional argument but 2 were given
```
cause Passing a raw string directly as the first argument to `Bounce` after version 3.0, when it expects an `email.message.Message` object.

fix Ensure you are passing an `email.message.Message` object. If you have a string, parse it first: `from email import message_from_string; msg = message_from_string(your_email_string); bounce = Bounce(msg)`.
```
AttributeError: 'Bounce' object has no attribute 'is_bounce'
```
cause Attempting to call `is_bounce()` as a method instead of accessing it as a property.

fix Remove the parentheses. Access it as a property: `if bounce.is_bounce:`.
```
ImportError: cannot import name 'Detector' from 'flufl.bounce'
```
cause The `Detector` class was removed in version 4.0.

fix The `Detector` class is no longer available. Use the `Bounce` class directly, which now incorporates the detection logic. For example, `bounce = Bounce(email_message); if bounce.is_bounce:`.

Warnings

breaking The `Bounce` constructor now strictly requires an `email.message.Message` object. Passing a raw string will result in a TypeError.
Fix: Before passing to `Bounce`, convert your raw email string or bytes using `email.message_from_string()` or `email.message_from_bytes()` from the standard library's `email` module. Example: `msg = message_from_string(raw_email_content); bounce = Bounce(msg)`.
breaking The `is_bounce` attribute has changed from a method (`bounce.is_bounce()`) to a property (`bounce.is_bounce`).
Fix: Remove parentheses when accessing `is_bounce`. Change `bounce.is_bounce()` to `bounce.is_bounce`.
breaking Python 3.7 is no longer supported. The minimum required Python version is 3.8.
Fix: Upgrade your Python environment to 3.8 or newer to use `flufl-bounce` 4.0+.
breaking The `Detector` class has been removed. Its functionality is now integrated directly into the `Bounce` class.
Fix: Migrate your code to use the `Bounce` class directly for bounce detection and parsing. The `Bounce` object itself now encapsulates the detection logic.

Install

pip install flufl-bounce Install latest version

Imports

Bounce
wrong:
```
from flufl.bounce.bounce import Bounce
```
correct:
```
from flufl.bounce import Bounce
```
The primary class is directly under the flufl.bounce package.
message_from_string
```
from email import message_from_string
```
Commonly used with flufl.bounce to parse raw email content into an EmailMessage object.

Quickstart

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.")

view raw JSON →