mail-parser

4.2.1 · active · verified Sat Apr 11

mail-parser is a production-grade, RFC-compliant email parsing library that enhances the Python standard library's email module. It extracts all details into a comprehensive object, including headers, plain text and HTML bodies, attachments, and routing information, with a strong focus on security analysis and defect detection. It provides access to parsed elements as Python objects, raw strings, and JSON. The library is actively maintained.

Warnings

breaking Some parsing behavior for complex or malformed emails may have changed between versions 3.x and 4.x. A GitHub issue indicates a regression where emails parse successfully in 3.15.0 but fail in 4.0.0. Users upgrading from 3.x to 4.x should thoroughly test their email parsing routines, especially for edge cases.
Fix: Review existing parsing logic and test against the new version. Consult GitHub issues or the project's changelog for specific changes if parsing failures occur. Consider reporting new regressions if unaddressed.
gotcha Parsing Microsoft Outlook .msg files requires an external system dependency on Debian-based systems. You need to install `libemail-outlook-message-perl` for this functionality.
Fix: On Debian/Ubuntu: `sudo apt-get install libemail-outlook-message-perl`. For other operating systems, consult the project's documentation for equivalent dependencies or alternatives.
gotcha The `mail-parser` library can be confused with other similarly named Python packages (e.g., `fast_mail_parser`, `mailparse`, `msg-parser`) or web services (e.g., `Mailparser.io`). Ensure you are importing and using the correct library from the `SpamScope` organization.
Fix: Always verify the PyPI project page (https://pypi.org/project/mail-parser/) and the GitHub repository (https://github.com/SpamScope/mail-parser) to confirm you have the correct package. Use `pip install mail-parser` for installation.
gotcha When accessing the 'From' header, use `mail.from_` (with an underscore) instead of `mail.from` because `from` is a reserved keyword in Python. Attempting to use `mail.from` will result in a `SyntaxError`.
Fix: Always append an underscore when referring to the 'From' header attribute, e.g., `parsed_mail.from_`.

Install

pip install mail-parser Install with pip

Imports

mailparser
```
import mailparser
```
Main library import for accessing parsing functions.
parse_from_string
```
mail = mailparser.parse_from_string(raw_email_string)
```
One of several factory methods to parse emails from different sources (string, bytes, file, etc.).

Quickstart

Parses a raw email string and extracts basic headers and the plain text body. Demonstrates accessing structured email components like sender, subject, and body content.

import mailparser

raw_email = (
    "From: Sender Name <sender@example.com>\n"
    "To: Recipient Name <recipient@example.com>\n"
    "Subject: Test Email from mail-parser\n"
    "Content-Type: text/plain; charset=\"utf-8\"\n"
    "\n"
    "Hello, this is the plain text body of the email.\n"
    "It was parsed using the mail-parser library."
)

mail = mailparser.parse_from_string(raw_email)

print(f"From: {mail.from_}")
print(f"Subject: {mail.subject}")
if mail.text_plain:
    print(f"Body: {mail.text_plain[0]}")

# Example of accessing the 'to' address list
for recipient in mail.to:
    print(f"To Name: {recipient[0]}, Address: {recipient[1]}")

view raw JSON →