Open Source Python Library for Email Parsing

Getting Started with flanker

To get started with flanker, you need Python headers installed first. On Ubuntu, run `sudo apt-get install python-dev`; on Fedora, use `sudo yum install python-devel`. Then install via pip: `pip install flanker`. Alternatively, clone the [flanker GitHub](https://github.com/mailgun/flanker) repo and run `pip install -e .`. The library is lightweight, with minimal dependencies, and ready for production use. Detailed documentation and API references are available in the project’s GitHub repository.

# Ubuntu: install Python headers
sudo apt-get install python-dev

# Install via pip
pip install flanker

# Or clone and install from GitHub
git clone git@github.com:mailgun/flanker.git
cd flanker
pip install -e .

Parse and Validate Email Addresses

flanker provides powerful tools for parsing and validating email addresses. You can parse a single address with display name, validate against DNS/MX records, and check ESP grammar rules. The library supports strict and lenient parsing modes, and can return parsed addresses or `None` for invalid inputs. It also handles address lists, returning parsed addresses and unparsable fragments separately. This makes it ideal for cleaning user input, validating bulk imports, and ensuring data integrity in email-driven workflows.

from flanker.addresslib import address

# Parse single address with display name
addr = address.parse('John Doe <john@example.com>')
print(addr)  # John Doe <john@example.com>

# Validate with DNS/MX checks
valid = address.validate_address('john@mailgun.com')
print(valid)  # john@mailgun.com

# Parse list and separate valid/unparseable
parsed, failed = address.parse_list(['john@example.com, @invalid'], as_tuple=True)
print(parsed, failed)  # [john@example.com], ['@invalid']

Parse MIME Messages

flanker’s MIME parsing module (`flanker.mime`) enables developers to parse raw email messages into structured Python objects. You can extract headers, decode bodies, detect content types, and navigate multipart structures with ease. The library handles encoding, charset conversion, and nested MIME parts automatically. With predicates like `is_multipart()` and `is_singlepart()`, you can programmatically inspect message structure and process each part accordingly—ideal for building email clients, archiving systems, or automated processing pipelines.

from flanker import mime

# Parse raw MIME message
msg = mime.from_string(raw_message)

# Extract headers
headers = msg.headers.items()

# Check content type
is_multipart = msg.content_type.is_multipart()

# Decode body (handles multipart automatically)
for part in msg.parts:
    print(f"Content-Type: {part.content_type}")
    print(f"Body: {part.body}")

Extract Headers and Metadata

flanker provides rich access to email headers and metadata through its MIME parsing API. Headers are returned as a Unicode multi-value dictionary, supporting case-insensitive lookups and structured values (e.g., `Content-Type` parsed into type and parameters). You can retrieve sender, recipient, subject, date, and custom headers with ease. This is especially useful for email indexing, spam filtering, compliance auditing, and building search-friendly email archives where precise header parsing is critical.

from flanker import mime

msg = mime.from_string(raw_message)

# Get all headers as list of tuples
for key, value in msg.headers.items():
    print(f"{key}: {value}")

# Access structured content-type
ctype = msg.content_type
print(f"Type: {ctype.type}, Boundary: {ctype.boundary}")

# Get raw header value
raw_from = msg.headers.get('From')
print(raw_from)  # Bob <bob@example.com>

Handle Multipart Messages and Attachments

flanker simplifies working with complex multipart messages, including those with nested parts and attachments. You can iterate over `msg.parts` to access each MIME part, inspect its content type, and decode its body. The library automatically handles base64 and quoted-printable decoding, charset conversion, and boundary detection. This makes it straightforward to extract text/plain and text/html versions, save attachments, or rebuild messages for forwarding or archival—ideal for email clients, backup tools, and compliance systems.

from flanker import mime

msg = mime.from_string(raw_message)

# Iterate over parts
for part in msg.parts:
    if part.content_type.is_text():
        print(f"Text part: {part.body}")
    elif part.content_type.is_attachment():
        filename = part.content_type.filename
        payload = part.body
        print(f"Attachment: {filename}, size: {len(payload)}")