mail-parser

For security and forensics, mail-parser identifies structural anomalies and RFC non-compliance.

• defects: A property that identifies RFC non-compliance issues.
• defects_categories: Provides categorized defect types to help identify potential malicious intent or malformed structures.

Every parsed element in mail-parser is accessible via three distinct patterns, allowing you to choose between structured data, standardized JSON, or the original raw content:

1. Native Python objects: Use the property name directly (e.g., mail.to) to get structured, typed data (like lists of recipient objects or timestamps).
2. JSON serialization: Append _json to the property name (e.g., mail.to_json) to get a JSON-serialized string, ideal for APIs or databases.
3. Raw strings: Append _raw to the property name (e.g., mail.to_raw) to get the original, unprocessed header content exactly as it appeared in the email.

Example:

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

If you are contributing to the project, use uv to manage dependencies in an isolated environment.

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

To parse Microsoft Outlook .msg files, you must install the [outlook] extra. This installs extract-msg, a pure-Python backend that is the recommended way to handle .msg files.

If extract-msg is installed, mail-parser will use it by default. If it is not available, the library will attempt to fall back to the deprecated msgconvert Perl tool, but it is highly recommended to use the Python backend to avoid compatibility issues and deprecation warnings.

pip install mail-parser[outlook]

Install the mail-parser package using pip. This requires Python 3 to be installed on your system.

pip install mail-parser

You can use the official Docker image for containerized workflows.

Quick Start

Run the container and mount a local directory to access email files:

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

Using Docker Compose

To use the included docker-compose.yml configuration:

sudo docker-compose up

You can run the mail-parser service using Docker Compose. The service is configured to run with the --json flag and processes a specific file path. To use this setup, ensure you mount your local mail directory to the container's /mails/ directory as a read-only volume.

version: '2.1'

services:
  mailparser:
    image: fmantuano/spamscope-mail-parser:develop
    command: --json -f /mails/mail_test_1
    container_name: mailparser
    volumes:
      - ~/mails/:/mails/:ro

To access non-standard or vendor-specific headers (e.g., X-MSMail-Priority), replace the hyphens in the header name with underscores.

Example:

mail.X_MSMail_Priority

Use the write_attachments method to write all parsed attachments to a specified directory.

mail.write_attachments(base_path)

Once an email is parsed, you can access its components through various properties. Key properties include:

• attachments: List of all attachments with metadata.
• body: Complete message body.
• date: Parsed datetime object (UTC).
• defects: List of RFC compliance defects (useful for security analysis).
• defects_categories: Categorized defect types.
• from_: Sender information.
• to: Recipient information.
• subject: Email subject.
• headers: All headers as a structured object.
• message: The underlying email.message.Message object.
• text_plain / text_html: Lists of plain text or HTML body parts.
• get_server_ipaddress(trust="..."): Retrieves a reliable sender IP address.

# Example of accessing properties
print(mail.subject)
print(mail.from_)
print(mail.defects)

Import the mailparser module and use the appropriate factory function based on your input source:

• parse_from_bytes(byte_mail): Parse from a bytes object.
• parse_from_file(f): Parse from a file path.
• parse_from_file_msg(outlook_mail): Parse an Outlook .msg file.
• parse_from_file_obj(fp): Parse from a file object.
• parse_from_string(raw_mail): Parse from a raw string.

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

The library uses a structured exception hierarchy for 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
  • MailParserReceivedParsingError: Raised when a received header cannot be parsed