mail-parser is a production-grade, RFC-compliant email parsing library that goes far beyond a simple wrapper for Python's email module. It transforms raw email messages into richly structured Python objects with unparalleled precision, making complex email processing accessible and reliable.

As the battle-tested foundation of SpamScope—a powerful email security and threat analysis platform—mail-parser has proven itself in demanding production environments where accuracy and security matter most.

🔒 Security-First Design: Built specifically for email security analysis and digital forensics, mail-parser excels at detecting malformed structures, hidden content, and RFC non-compliance that could indicate malicious intent.

🎯 Comprehensive Parsing: Extracts every component of an email—headers, bodies (plain text and HTML), attachments, metadata, routing information, and even subtle defects that other parsers miss.

🔍 Multi-Format Access: Every parsed element is accessible in three formats (Python object, raw string, and JSON), enabling seamless integration with any workflow or downstream system.

🛡️ Defect Detection: Identifies and categorizes RFC violations, malformed MIME boundaries, and structural anomalies that could hide malicious payloads or bypass security filters.

📧 Outlook Support: Native handling of Microsoft Outlook .msg files alongside standard email formats, making it versatile for diverse email ecosystems.

⚡ Production-Ready: Trusted by security professionals and developers worldwide, with extensive test coverage and proven reliability in high-stakes environments.

mail-parser is fully compatible with Python 3, ensuring modern performance and reliability.

mail-parser converts Outlook .msg files to standard .eml before parsing. Two conversion backends are supported:

1. extract-msg (recommended, pure Python). No external tools required. Install the optional extra:

   pip install mail-parser[outlook]

2. msgconvert (deprecated, external Perl tool). Requires the libemail-outlook-message-perl system package:

   apt-get install libemail-outlook-message-perl   # Debian-based systems
   apt-cache show libemail-outlook-message-perl     # package details

Backend precedence: when extract-msg is installed it is used first. Only when it is not available does mail-parser fall back to the msgconvert external tool, logging a deprecation warning. If neither backend is available, parse_from_file_msg() raises MailParserOSError telling you to install either path.

⚠️ Deprecated: the msgconvert external-tool backend is deprecated and will be removed in a future release. Migrate to the pure-Python backend with pip install mail-parser[outlook].

💥 BREAKING CHANGE: the default .msg conversion backend changed. When extract-msg is installed it is now preferred over msgconvert. The two converters produce different intermediate .eml output, so some parsed fields (header ordering, encoding edge cases, attachment naming) can differ from the previous msgconvert-only behavior. Downstream code asserting on exact .msg-derived output may need updating.

mail-parser can be downloaded, used, and modified free of charge. It is available under the Apache 2 license.

mail-parser is a labor of love and commitment to the open-source community. Thousands of developers and security professionals worldwide rely on this library for critical email processing and threat analysis. Your support directly fuels continued innovation and excellence.

Your contribution—no matter the size—makes a real difference. By supporting mail-parser, you enable us to:

• Advance Security Capabilities: Develop cutting-edge detection mechanisms for emerging email threats and attack vectors.
• Expand Format Support: Add compatibility with new email formats and standards as they evolve.
• Enhance Performance: Optimize parsing speed and memory efficiency for large-scale deployments.
• Maintain Excellence: Ensure comprehensive testing, documentation, and bug-free releases that you can trust in production.
• Foster Community: Respond to issues, review contributions, and build a thriving ecosystem around email security.
• Stay RFC-Compliant: Keep pace with evolving email standards and specifications to ensure maximum compatibility.

Every donation, whether $5 or $500, directly funds development time and infrastructure costs. Join the community of supporters who believe in accessible, reliable, and secure email parsing for everyone.

Or contribute with Bitcoin:

Bitcoin Address: bc1qxhz3tghztpjqdt7atey68s344wvmugtl55tm32

Thank you for supporting the evolution of mail-parser!

Explore mail-parser on these platforms:

• FreeBSD port
• Arch User Repository
• REMnux

mail-parser transforms raw email messages into comprehensive, RFC-compliant Python objects that faithfully mirror the structure defined by IETF email protocol standards. Each property of the parsed object directly corresponds to standard RFC headers—"From", "To", "Cc", "Bcc", "Subject", and many more—providing intuitive, Pythonic access to every email component.

The library extracts and structures every aspect of an email message:

• Multi-format Bodies: Both plain text and HTML body content, cleanly separated and accessible.
• Complete Attachments: Full metadata extraction including filename, content type, encoding, content disposition, content-ID, charset, and base64-encoded payloads.
• Routing Intelligence: Parsed "Received" headers revealing the complete email journey, including hop-by-hop analysis with timestamps, delays, server information, and envelope data.
• Advanced Diagnostics: Timestamp parsing with timezone detection, defect identification for RFC non-compliance, and structural anomaly detection.
• Custom Headers: Full support for non-standard and vendor-specific headers using intuitive underscore substitution for hyphenated names.

Every parsed element offers three distinct access patterns for maximum flexibility:

• Native Python objects: Structured, typed data ready for immediate programmatic use (mail.to, mail.date, mail.attachments).
• Raw strings: Original, unprocessed header content preserving exact formatting (mail.to_raw, mail.subject_raw).
• JSON serialization: Clean, standardized JSON representations for easy integration with APIs, databases, or other tools (mail.to_json, mail.headers_json).

This versatile architecture makes mail-parser exceptionally powerful for diverse use cases—from security analysis and forensics to email migration, compliance auditing, and automated processing pipelines.

Standard RFC Headers (directly accessible as properties):

• bcc - Blind carbon copy recipients
• cc - Carbon copy recipients
• date - Parsed timestamp with timezone support
• delivered_to - Final delivery address
• from_ - Sender address (underscore used since from is a Python keyword)
• message_id - Unique message identifier
• received - Parsed routing chain with hop-by-hop details
• reply_to - Reply-to address
• subject - Email subject line
• to - Primary recipients

Additional Parsed Components:

• body - Complete message body
• text_html - HTML body parts (list)
• text_plain - Plain text body parts (list)
• headers - All headers as a structured object. Keys are the header names exactly as they appear in the message, and every header is reported — including names that match a MailParser method or property (Parse, Message, Headers_json) and names containing underscores (X_Spam_Flag). Such names are always resolved as headers, never as attributes, and are never rewritten.
• attachments - Complete attachment metadata and payloads
• get_server_ipaddress() - Reliable sender IP extraction with trust levels. Only the from clause of the first trusted Received header is searched, with the sender-supplied HELO name removed, and the result is None when that hop names no public IP. Attribution never falls back to older Received headers, which the sender is free to forge.
• to_domains - Extracted recipient domains for analysis
• timezone - Detected timezone information
• defects - RFC compliance issues for security analysis
• defects_categories - Categorized defect types

The attachments property returns a list of dictionaries, each containing comprehensive metadata:

• binary - Boolean flag indicating binary content
• charset - Character encoding of the attachment
• content_transfer_encoding - Transfer encoding method (e.g., base64, quoted-printable)
• content-disposition - Disposition type (attachment, inline, etc.)
• content-id - Content identifier for referencing within HTML bodies
• filename - Original decoded filename from the email. This is untrusted input; never use it directly to construct a filesystem path.
• safe_filename - Filename with directory components removed and truncated to fit the filesystem name limit, or None when the original has no usable basename. When saving attachments, prefer write_attachments() for full validation and collision handling.
• mail_content_type - MIME content type
• payload - Base64-encoded attachment data, ready for decoding or storage. An attachment is kept as bytes: whatever encoding it was sent with, it is re-encoded to base64 and reports base64 as its content_transfer_encoding, so the payload always matches the encoding it declares and hashes like the file the recipient received. Only base64 parts keep their original wire text, which is already lossless

To access custom or vendor-specific headers, replace hyphens with underscores. For example, to access the X-MSMail-Priority header:

mail.X_MSMail_Priority

This underscore-for-hyphen convenience, and the _json / _raw suffixes, apply only to attribute access written by you. Names read out of a message — the keys of mail and headers — are looked up literally, so a header genuinely named X_Spam_Flag or Subject_json keeps its own name and its own value. Attribute names beginning with an underscore are not headers and raise AttributeError.

The received header is intelligently parsed into individual hops, revealing the complete email routing path. Each hop contains structured fields:

• by - Receiving mail server
• date - Timestamp of receipt (original timezone)
• date_utc - Normalized UTC timestamp
• delay - Time elapsed between consecutive hops
• envelope_from - SMTP envelope sender
• envelope_sender - Alternative envelope sender field
• for - Intended recipient
• from - Sending mail server
• hop - Sequential hop number
• with - Protocol used for transmission (SMTP, ESMTP, etc.)

Critical Security Feature: mail-parser detects and reports structural defects in email messages.

The defects property identifies RFC non-compliance issues that may indicate malformed or malicious emails—a crucial capability for security analysis and threat detection.

Multi-Format Property Access Pattern:

All parsed properties provide three access variants using intuitive suffixes:

• property_name - Returns structured Python object
• property_name_json - Returns JSON-serialized representation
• property_name_raw - Returns original, unprocessed header string

Example usage:

mail.to          # Python list of recipient objects
mail.to_json     # JSON string representation
mail.to_raw      # Original "To:" header string as it appears in the email

The command-line tool outputs parsed emails in JSON format by default for easy integration with other tools and pipelines.

Email structural defects are not merely technical curiosities—they represent potential security vulnerabilities that sophisticated attackers actively exploit to bypass spam filters, antivirus scanners, and email security gateways.

Malformed MIME boundaries, for example, can conceal illegitimate epilogue sections containing:

• Malware Payloads: Executable files or scripts hidden in non-standard message parts
• Phishing Links: Obfuscated URLs that bypass pattern-matching filters
• Command-and-Control Data: Encoded instructions for compromised systems
• Data Exfiltration: Steganographically hidden sensitive information

mail-parser was specifically engineered for security analysis and digital forensics, with defect detection as a core feature rather than an afterthought. The library captures and categorizes even subtle structural anomalies that other parsers silently ignore or mishandle.

By leveraging mail-parser's defect detection, security teams can:

• Expose Hidden Content: Discover deliberately obfuscated message parts that may contain malicious payloads.
• Identify Attack Patterns: Recognize non-standard formatting techniques used by threat actors to evade detection.
• Enable Deep Forensics: Conduct thorough structural analysis of suspicious emails during incident response.
• Strengthen Defenses: Build more resilient email security rules based on identified defect patterns.
• Ensure Compliance: Verify that outbound emails meet RFC standards to avoid delivery issues.

This robust defect detection mechanism has made mail-parser the trusted choice for security platforms like SpamScope, where identifying malicious intent hidden in structural anomalies can mean the difference between a blocked threat and a successful attack.

Fedele Mantuano: LinkedIn

mail-parser requires Python 3 and can be installed in seconds using pip. Follow these steps:

1. Ensure Python 3 is installed on your system.
2. Open your terminal or command prompt.
3. Install mail-parser from PyPI:

pip install mail-parser

1. (Optional) Verify the installation:

pip show mail-parser

For contributors and developers who want to work with the source code, we recommend using uv for dependency management:

git clone https://github.com/SpamScope/mail-parser.git
cd mail-parser
uv sync

This setup installs all development and testing dependencies in an isolated virtual environment, ensuring a clean and reproducible development workflow.

For comprehensive documentation about uv, visit the official uv documentation.

Import the mailparser module and use the convenient factory functions:

import mailparser

mail = mailparser.parse_from_bytes(byte_mail)      # Parse from bytes object
mail = mailparser.parse_from_file(f)               # Parse from file path
mail = mailparser.parse_from_file_msg(outlook_mail) # Parse Outlook .msg file
mail = mailparser.parse_from_file_obj(fp)          # Parse from file object
mail = mailparser.parse_from_string(raw_mail)      # Parse from string

Once parsed, access all email components through intuitive properties:

mail.attachments              # List of all attachments with metadata
mail.body                     # Complete message body
mail.date                     # Parsed datetime object (UTC)
mail.defects                  # List of RFC compliance defects
mail.defects_categories       # Categorized defect types
mail.delivered_to             # Delivery address
mail.from_                    # Sender information
mail.get_server_ipaddress(trust="my_server_mail_trust")  # Reliable sender IP
mail.headers                  # All headers as structured object
mail.mail                     # Fully tokenized mail object
mail.message                  # Underlying email.message.Message object
mail.message_as_string        # Reconstructed message as string
mail.message_id               # Unique message identifier
mail.received                 # Parsed routing information (hop-by-hop)
mail.subject                  # Email subject
mail.text_plain               # Plain text body parts (list)
mail.text_html                # HTML body parts (list)
mail.text_not_managed         # Unprocessed text parts (check logs for subtypes)
mail.to                       # Recipient information
mail.to_domains               # Extracted recipient domains
mail.timezone                 # Timezone information (offset from UTC)
mail.mail_partial             # Partial mail object (main parts only)

Write all attachments to a specified directory:

mail.write_attachments(base_path)

Attachment filenames are supplied by the email sender. The filename value in mail.attachments intentionally preserves that untrusted metadata for analysis and display. Do not pass it directly to open() or join it to a directory. The safe_filename field provides a sanitized basename when one exists, but applications saving files should prefer write_attachments(), which also validates containment, rejects symlink destinations, and deduplicates names within the attachment batch. Deduplication is case-insensitive, because APFS, exFAT and SMB collapse Invoice.pdf and invoice.pdf onto a single file.

A single unusable attachment never costs the rest of the batch: write_attachments() logs a warning and moves on when a filename cannot be sanitized, a payload cannot be decoded, or the write itself fails, so the remaining attachments are still saved. A containment failure is not treated this way: it raises MailParserPathError and stops the batch.

After installing mail-parser with pip, you can use the mailparser command-line tool for quick email analysis, batch processing, or integration with shell scripts and pipelines.

usage: mailparser [-h] (-f FILE | -s STRING | -k)
                   [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}] [-j] [-b]
                   [-a] [-r] [-t] [-dt] [-m] [-u] [-c] [-d] [-o]
                   [-i Trust mail server string] [-p] [-z] [-v]

Wrapper for email Python Standard Library

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  Raw email file (default: None)
  -s STRING, --string STRING
                        Raw email string (default: None)
  -k, --stdin           Enable parsing from stdin (default: False)
  -l {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}, --log-level {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Set log level (default: WARNING)
  -j, --json            Show the JSON of parsed mail (default: False)
  -b, --body            Print the body of mail (default: False)
  -a, --attachments     Print the attachments of mail (default: False)
  -r, --headers         Print the headers of mail (default: False)
  -t, --to              Print the to of mail (default: False)
  -dt, --delivered-to   Print the delivered-to of mail (default: False)
  -m, --from            Print the from of mail (default: False)
  -u, --subject         Print the subject of mail (default: False)
  -c, --receiveds       Print all receiveds of mail (default: False)
  -d, --defects         Print the defects of mail (default: False)
  -o, --outlook         Analyze Outlook msg (default: False)
  -i Trust mail server string, --senderip Trust mail server string
                        Extract a reliable sender IP address heuristically
                        (default: None)
  -p, --mail-hash       Print mail fingerprints without headers (default:
                        False)
  -z, --attachments-hash
                        Print attachments with fingerprints (default: False)
  -sa, --store-attachments
                        Store attachments on disk (default: False)
  -ap ATTACHMENTS_PATH, --attachments-path ATTACHMENTS_PATH
                        Path where store attachments (default: /tmp)
  -v, --version         show program's version number and exit

It takes as input a raw mail and generates a parsed object.

Parse an email file and output as formatted JSON:

mailparser -f example_mail -j

Extract only the subject and sender:

mailparser -f example_mail -u -m

Analyze an Outlook .msg file with defect detection:

mailparser -f email.msg -o -d -j

Parse from stdin (useful for pipelines):

cat raw_email.eml | mailparser -k -j

See the transformation from raw email to beautifully parsed JSON output.

mail-parser uses a well-structured exception hierarchy for precise error handling:

MailParserError: Base MailParser Exception
|
\── MailParserOutlookError: Raised with Outlook integration errors
|
\── MailParserEnvironmentError: Raised when the environment is not correct
|
\── MailParserOSError: Raised when there is an OS error
|
\── MailParserPathError: Raised when an attachment escapes the output directory
|
\── MailParserReceivedParsingError: Raised when a received header cannot be parsed
|
\── MailParserRecursionError: Raised when a message is nested too deeply to parse

A pre-built Docker image is available for easy deployment and containerized workflows. Find the official image on Docker Hub.

After installing Docker, run the containerized mail-parser:

sudo docker run -it --rm -v ~/mails:/mails fmantuano/spamscope-mail-parser

This command mounts your local ~/mails directory into the container at /mails, allowing mail-parser to access your email files. You can pass any command-line options supported by mail-parser.

For more complex setups, a docker-compose.yml file is included in the repository. Run it with:

sudo docker-compose up

The default configuration includes:

• Read-only mount of your local ~/mails directory to /mails in the container.
• A test command demonstrating mail-parser functionality.

Customize the docker-compose.yml file to adjust mount points, command-line options, or environment variables for your specific use case.