Install & Compatibility
Where this runs
tested against v0.2.3 · 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.257s · 18.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.216s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse_addresses
✓ from mailbits import parse_addresses
format_addresses
✓ from mailbits import format_addresses
message2email
✓ from mailbits import message2email
✗ from mailbits.converters import message2email
All primary utilities are directly importable from the top-level `mailbits` package.
email2dict
✓ from mailbits import email2dict
ContentType
✓ from mailbits import ContentType
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.
from email.message import EmailMessage
from mailbits import parse_addresses, format_addresses, email2dict
# Example 1: Parsing and formatting addresses
address_string = '"John Doe" <john.doe@example.com>, "Jane Smith" <jane.smith@test.org>'
parsed_addresses = parse_addresses(address_string)
print(f"Parsed Addresses: {parsed_addresses}")
formatted_addresses = format_addresses(parsed_addresses)
print(f"Formatted Addresses: {formatted_addresses}")
# Example 2: Converting an EmailMessage to a dictionary
msg = EmailMessage()
msg['Subject'] = 'Hello from Mailbits'
msg['From'] = 'sender@example.com'
msg['To'] = 'recipient@example.com'
msg.set_content('This is a test email body.')
msg_dict = email2dict(msg)
print(f"\nEmail as Dictionary: {msg_dict}")
Debug
Known issues
gotchaWhen 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.fixAlways 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.
affects: <0.2.0 (conceptual)
gotchaThe `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.fixFor 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()`.
affects: All
breakingAs 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.fixPin `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.
affects: All 0.x.x versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mailbits.converters'
Attempting to import utilities from a submodule (e.g., `converters`) that are directly exposed at the top level of the `mailbits` package.
fixImport directly from `mailbits`: `from mailbits import message2email, email2dict`.
TypeError: argument must be Message or EmailMessage, not str
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.
fixEnsure 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)`.
AttributeError: 'Address' object has no attribute 'name' (or 'mailbox', 'host')
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.
fixUse `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').
Upgrade
Version history
0.2.3latest on PyPI · released Nov 29, 2025
Audit
Dependencies
No dependency data recorded yet.