Mailbits

0.2.3 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'mailbits.converters'
```
cause Attempting to import utilities from a submodule (e.g., `converters`) that are directly exposed at the top level of the `mailbits` package.

fix Import directly from `mailbits`: `from mailbits import message2email, email2dict`.
```
TypeError: argument must be Message or EmailMessage, not str
```
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.

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)`.
```
AttributeError: 'Address' object has no attribute 'name' (or 'mailbox', 'host')
```
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.

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

Warnings

gotcha 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.
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.
gotcha 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.
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()`.
breaking 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.
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.

Install

pip install mailbits Install stable version

Imports

parse_addresses
```
from mailbits import parse_addresses
```
format_addresses
```
from mailbits import format_addresses
```
message2email
wrong:
```
from mailbits.converters import message2email
```
correct:
```
from mailbits import message2email
```
All primary utilities are directly importable from the top-level `mailbits` package.
email2dict
```
from mailbits import email2dict
```
ContentType
```
from mailbits import ContentType
```

Quickstart

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

view raw JSON →