all2md.parsers.eml

Email (EML) to AST converter.

This module provides conversion from email messages to AST representation. It replaces direct markdown string generation with structured AST building.

all2md.parsers.eml.format_eml_date(dt: datetime | None, options: EmlOptions) → str

Format datetime according to EmlOptions configuration.

Parameters:

• dt (datetime.datetime | None) – Datetime to format.

• options (EmlOptions) – Configuration options for date formatting.

Returns:

Formatted date string, or empty string if dt is None.

Return type:

str

all2md.parsers.eml.extract_message_content(message: EmailMessage | Message, options: EmlOptions) → tuple[str, bool]

Extract body content from an email message with enhanced multipart handling.

Processes both simple and multipart email messages to extract readable content. For multipart messages, prefers text/plain content but can fall back to text/html (optionally HTML-to-Markdown converted) and then to RTF.

Parameters:

• message (EmailMessage | Message) – Email message object from Python’s email library to extract content from.

• options (EmlOptions) – Configuration options for content extraction and processing.

Returns:

(content, is_markdown). is_markdown is True when the content is already Markdown – produced by converting an HTML or RTF body – and so should be parsed back into rich AST nodes rather than treated as plain text. It is False for plain-text bodies and for raw (unconverted) HTML.

Return type:

tuple[str, bool]

Notes

• For multipart/alternative: prefers text/plain, falls back to text/html, then RTF

• For multipart/mixed: combines all text parts of the winning type

• Optionally converts HTML to Markdown

• Manages different character encodings with UTF-8 fallback

• Uses error-safe decoding to handle malformed content

all2md.parsers.eml.convert_eml_html_to_markdown(html_content: str, options: EmlOptions) → str

Convert HTML content to Markdown.

Parameters:

• html_content (str) – HTML content to convert.

• options (EmlOptions) – Configuration options for conversion.

Returns:

Converted Markdown content.

Return type:

str

all2md.parsers.eml.convert_eml_rtf_to_markdown(part: EmailMessage | Message, options: EmlOptions) → str

Convert an RTF email body part to Markdown.

Decodes the part’s payload to raw bytes and runs it through the RTF parser, rendering the result to Markdown. RTF bodies show up in emails exported from Outlook via libpst/readpst; unlike plain text or HTML they carry no useful representation as-is, so they are always converted rather than passed through.

Parameters:

• part (EmailMessage | Message) – The RTF body part (application/rtf or text/rtf).

• options (EmlOptions) – Configuration options for conversion.

Returns:

Converted Markdown content, or an empty string when the part is empty or the optional RTF dependency is unavailable.

Return type:

str

all2md.parsers.eml.parse_single_message(msg: EmailMessage | Message, options: EmlOptions) → dict[str, Any]

Parse a single email message into a structured dictionary with enhanced processing.

Extracts all relevant metadata and content from an email message object, including headers, dates, recipients, and message content. Handles date parsing with fallback hierarchy and advanced content extraction.

Parameters:

• msg (EmailMessage | Message) – Email message object from Python’s email library containing the message to parse.

• options (EmlOptions) – Configuration options for parsing and processing.

Returns:

Dictionary containing parsed email data with keys: - ‘from’: sender email address (normalized if enabled) - ‘to’: recipient email address(es) (normalized if enabled) - ‘cc’: carbon copy recipients (if present and normalized if enabled) - ‘bcc’: blind carbon copy recipients (if present and normalized if enabled) - ‘subject’: email subject line - ‘date’: parsed datetime object in UTC (or None) - ‘content’: extracted text content - ‘message_id’: unique message identifier - ‘in_reply_to’: reference to replied message - ‘references’: message thread references - ‘raw_headers’: raw header values (if preserve_raw_headers enabled)

Return type:

dict[str, Any]

Notes

• Uses fallback date hierarchy: Date -> Sent -> Received

• Converts dates to UTC timezone for consistency

• Extracts content with multipart handling and HTML conversion

• Preserves thread information through message IDs and references

• Optionally normalizes headers and preserves raw values

all2md.parsers.eml.split_chain(content: str, options: EmlOptions) → list[dict[str, Any]]

Split email chain content into individual message components with enhanced detection.

Parses a concatenated email chain text and separates it into individual message dictionaries by detecting email headers, reply separators, and quoted content boundaries. Uses multiple patterns for robust detection.

Parameters:

• content (str) – Raw email chain content containing multiple concatenated messages with headers like “From:”, “Date:”, “To:”, “Subject:”.

• options (EmlOptions) – Configuration options for chain splitting and content processing.

Returns:

List of dictionaries, each representing an individual email with extracted metadata including: - ‘from’: sender information - ‘to’: recipient information - ‘subject’: email subject - ‘date’: parsed datetime object in UTC - ‘content’: message body content - ‘cc’: carbon copy recipients (if present)

Return type:

list[dict[str, Any]]

Notes

• Uses enhanced regex patterns for better header detection

• Detects common reply separators like “On <date>, <name> wrote:”

• Handles both “Date:” and “Sent:” date formats

• Preserves content that doesn’t match header patterns

• Converts dates to UTC timezone for consistency

• Returns single-item list if no chain splitting is detected

all2md.parsers.eml.process_email_attachments(msg: Message, options: EmlOptions) → tuple[str, dict[str, str]]

Process email attachments and return markdown representation.

Extracts attachments from an email message and processes them according to the specified attachment mode.

Parameters:

• msg (Message) – Email message object containing attachments

• options (EmlOptions) – Configuration options for attachment processing

Returns:

Tuple of (markdown representation of attachments, footnotes dict)

Return type:

tuple[str, dict[str, str]]

all2md.parsers.eml.clean_message(raw: str, options: EmlOptions) → str

Clean and normalize email message content with enhanced processing.

Processes raw email content to remove security-related URL redirects, clean up quoted message formatting, and normalize line structures. Uses configurable patterns for comprehensive cleaning.

Parameters:

• raw (str) – Raw email message content that may contain URL redirects, quoted text markers, and other email client formatting artifacts.

• options (EmlOptions) – Configuration options for content cleaning and processing.

Returns:

Cleaned message content with unwanted elements removed and quote formatting normalized according to configuration.

Return type:

str

Notes

• Removes lines containing configured URL wrapper domains

• Handles various quote prefixes (>, >>, etc.) if quote cleaning enabled

• Converts standalone quote markers to empty lines

• Preserves overall message structure and readability

• Configurable URL cleaning patterns for different security services

class all2md.parsers.eml.EmlToAstConverter

Bases: BaseParser

Convert email messages to AST representation.

This converter processes parsed email data and builds an AST that can be rendered to various markdown flavors.

Parameters:

options (EmlOptions or None) – Conversion options

Initialize the EML parser with options and progress callback.

__init__(options: EmlOptions | None = None, progress_callback: Callable[[ProgressEvent], None] | None = None)

Initialize the EML parser with options and progress callback.

parse(input_data: str | Path | IO[bytes] | bytes) → Document

Parse EML file into an AST Document.

Parameters:

input_data (str, Path, IO[bytes], or bytes) – The input email document to parse. Can be: - File path (str or Path) - File-like object in binary mode - Raw email bytes

Returns:

AST Document node representing the parsed email structure

Return type:

Document

Raises:

• MalformedFileError – If parsing fails due to invalid email format

• ParsingError – If content processing fails

• ValidationError – If input type is not supported

format_email_chain_as_ast(eml_chain: list[dict[str, Any]]) → Document

Convert email chain to AST Document.

Parameters:

eml_chain (list[dict[str, Any]]) – List of email dictionaries with ‘from’, ‘to’, ‘subject’, ‘date’, ‘content’

Returns:

AST document node

Return type:

Document

extract_metadata(document: Any) → DocumentMetadata

Extract metadata from email message.

Parameters:

document (EmailMessage | Message) – Email message object

Returns:

Extracted metadata

Return type:

DocumentMetadata