{"id":8176,"library":"flufl-bounce","title":"flufl.bounce: Email Bounce Detectors","description":"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.","status":"active","version":"4.0","language":"en","source_language":"en","source_url":"https://github.com/flufl/flufl.bounce","tags":["email","bounce","mail","parser","delivery-failure"],"install":[{"cmd":"pip install flufl-bounce","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Internal dependency for enum functionality","package":"flufl-enum","optional":false},{"reason":"Internal dependency for internationalization","package":"flufl-i18n","optional":false}],"imports":[{"note":"The primary class is directly under the flufl.bounce package.","wrong":"from flufl.bounce.bounce import Bounce","symbol":"Bounce","correct":"from flufl.bounce import Bounce"},{"note":"Commonly used with flufl.bounce to parse raw email content into an EmailMessage object.","symbol":"message_from_string","correct":"from email import message_from_string"}],"quickstart":{"code":"from email import message_from_string\nfrom flufl.bounce import Bounce\n\n# Simulate a bounce email content\nbounce_email_content = \"\"\"\nFrom: MAILER-DAEMON@example.com\nTo: original_sender@example.com\nSubject: Undelivered Mail Returned to Sender\n\nThis is the mail system at host example.com.\n\nI'm sorry to have to inform you that your message could not be delivered to one or more recipients.\nIt's attached below.\n\n<nonexistent@example.com>: host mail.example.com[192.0.2.1] said: 550 5.1.1\n    <nonexistent@example.com>: Recipient address rejected: User unknown\n\"\"\"\n\n# Parse the raw email string into an email.message.Message object\nmsg = message_from_string(bounce_email_content)\n\n# Create a Bounce object from the parsed message\nbounce = Bounce(msg)\n\nprint(f\"Is this a bounce message? {bounce.is_bounce}\")\nif bounce.is_bounce:\n    print(f\"Bounce type: {bounce.type}\")\n    print(f\"Failed recipients: {bounce.recipients}\")\n    print(f\"Diagnostic code: {bounce.diagnostic_code}\")\nelse:\n    print(\"Not recognized as a bounce by flufl.bounce.\")","lang":"python","description":"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."},"warnings":[{"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)`.","message":"The `Bounce` constructor now strictly requires an `email.message.Message` object. Passing a raw string will result in a TypeError.","severity":"breaking","affected_versions":"3.0, 4.0+"},{"fix":"Remove parentheses when accessing `is_bounce`. Change `bounce.is_bounce()` to `bounce.is_bounce`.","message":"The `is_bounce` attribute has changed from a method (`bounce.is_bounce()`) to a property (`bounce.is_bounce`).","severity":"breaking","affected_versions":"4.0+"},{"fix":"Upgrade your Python environment to 3.8 or newer to use `flufl-bounce` 4.0+.","message":"Python 3.7 is no longer supported. The minimum required Python version is 3.8.","severity":"breaking","affected_versions":"4.0+"},{"fix":"Migrate your code to use the `Bounce` class directly for bounce detection and parsing. The `Bounce` object itself now encapsulates the detection logic.","message":"The `Detector` class has been removed. Its functionality is now integrated directly into the `Bounce` class.","severity":"breaking","affected_versions":"4.0+"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","cause":"Attempting to initialize Bounce with a deprecated `message_string` keyword argument.","error":"TypeError: Bounce() got an unexpected keyword argument 'message_string'"},{"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)`.","cause":"Passing a raw string directly as the first argument to `Bounce` after version 3.0, when it expects an `email.message.Message` object.","error":"TypeError: Bounce() takes 1 positional argument but 2 were given"},{"fix":"Remove the parentheses. Access it as a property: `if bounce.is_bounce:`.","cause":"Attempting to call `is_bounce()` as a method instead of accessing it as a property.","error":"AttributeError: 'Bounce' object has no attribute 'is_bounce'"},{"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:`.","cause":"The `Detector` class was removed in version 4.0.","error":"ImportError: cannot import name 'Detector' from 'flufl.bounce'"}]}