{"id":7390,"library":"mailbits","title":"Mailbits","description":"Mailbits is a Python library that provides a small assortment of utility functions designed to work with Python's standard library `email` package, specifically its `Message`, `EmailMessage`, `Address`, and `Group` types. It offers functionalities like parsing and reassembling `Content-Type` strings, converting older `Message` objects to the newer `EmailMessage` format, transforming `Message` and `EmailMessage` instances into structured dictionaries, and robust parsing and formatting of email addresses. The current version is 0.2.3, and it appears to have an as-needed or sporadic release cadence, typical for focused utility libraries.","status":"active","version":"0.2.3","language":"en","source_language":"en","source_url":"https://github.com/jwodder/mailbits","tags":["email","email-parsing","email-formatting","email-utilities","python-standard-library"],"install":[{"cmd":"pip install mailbits","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"parse_addresses","correct":"from mailbits import parse_addresses"},{"symbol":"format_addresses","correct":"from mailbits import format_addresses"},{"note":"All primary utilities are directly importable from the top-level `mailbits` package.","wrong":"from mailbits.converters import message2email","symbol":"message2email","correct":"from mailbits import message2email"},{"symbol":"email2dict","correct":"from mailbits import email2dict"},{"symbol":"ContentType","correct":"from mailbits import ContentType"}],"quickstart":{"code":"from email.message import EmailMessage\nfrom mailbits import parse_addresses, format_addresses, email2dict\n\n# Example 1: Parsing and formatting addresses\naddress_string = '\"John Doe\" <john.doe@example.com>, \"Jane Smith\" <jane.smith@test.org>'\nparsed_addresses = parse_addresses(address_string)\nprint(f\"Parsed Addresses: {parsed_addresses}\")\nformatted_addresses = format_addresses(parsed_addresses)\nprint(f\"Formatted Addresses: {formatted_addresses}\")\n\n# Example 2: Converting an EmailMessage to a dictionary\nmsg = EmailMessage()\nmsg['Subject'] = 'Hello from Mailbits'\nmsg['From'] = 'sender@example.com'\nmsg['To'] = 'recipient@example.com'\nmsg.set_content('This is a test email body.')\n\nmsg_dict = email2dict(msg)\nprint(f\"\\nEmail as Dictionary: {msg_dict}\")","lang":"python","description":"This quickstart demonstrates how to use `mailbits` to parse and format email address strings, and how to convert an `EmailMessage` object from the standard library into a structured Python dictionary for easier manipulation or serialization."},"warnings":[{"fix":"Always check the type of your email message object. If you consistently use `EmailMessage` from Python 3.6+, `message2email` might be unnecessary unless you're processing varied inputs.","message":"When using `message2email()`, be aware that it specifically converts instances of the older `email.message.Message` class to the newer `email.message.EmailMessage`. If you're already working with `EmailMessage` objects, this function will return them unchanged. Ensure you understand the distinction between the two classes in Python's `email` module, especially when integrating with older codebases or third-party libraries that might still return `Message` objects.","severity":"gotcha","affected_versions":"<0.2.0 (conceptual)"},{"fix":"For critical applications, add validation or try-except blocks around address parsing/formatting, and thoroughly test with a wide range of real-world address formats. Consider sanitizing inputs before passing them to `parse_addresses()`.","message":"The `parse_addresses()` and `format_addresses()` functions are powerful, but they rely on RFC compliance. Malformed or highly unusual address strings might not parse as expected. While `mailbits` aims to be robust, edge cases exist.","severity":"gotcha","affected_versions":"All"},{"fix":"Pin `mailbits` to exact versions in production environments (e.g., `mailbits==0.2.3`) and thoroughly test when updating to a newer 0.x.x release.","message":"As a 0.x.x version library, `mailbits` does not strictly adhere to semantic versioning. Minor versions (e.g., 0.2.x to 0.3.x) *could* introduce breaking API changes without a major version increment. Always review release notes when upgrading.","severity":"breaking","affected_versions":"All 0.x.x versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Import directly from `mailbits`: `from mailbits import message2email, email2dict`.","cause":"Attempting to import utilities from a submodule (e.g., `converters`) that are directly exposed at the top level of the `mailbits` package.","error":"ModuleNotFoundError: No module named 'mailbits.converters'"},{"fix":"Ensure you construct a proper `email.message.EmailMessage` (or `Message`) object from your string content before passing it to `mailbits` utility functions. For example: `from email.message import EmailMessage; msg = EmailMessage(); msg.set_content(your_string_body)`.","cause":"Passing a plain string or an incorrect object type to functions like `message2email()` or `email2dict()`, which expect `email.message.Message` or `email.message.EmailMessage` objects.","error":"TypeError: argument must be Message or EmailMessage, not str"},{"fix":"Use `address_obj.display_name` for the display name (or an empty string if none) and `address_obj.addr_spec` for the actual email address (e.g., 'user@domain.com').","cause":"Attempting to access attributes like `name`, `mailbox`, or `host` directly on `email.headerregistry.Address` objects returned by `parse_addresses()`. `Address` objects use `display_name` and `addr_spec` for name and full address, respectively.","error":"AttributeError: 'Address' object has no attribute 'name' (or 'mailbox', 'host')"}]}