Headers

mail_intake.parsers.headers

Message header parsing utilities for Mail Intake.

This module provides helper functions for normalizing and extracting useful information from provider-native message headers.

The functions here are intentionally simple and tolerant of malformed or incomplete header data.

extract_sender

extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]

Extract sender email and optional display name from headers.

This function parses the From header and attempts to extract: - Sender email address - Optional human-readable display name

Parameters:

Name	Type	Description	Default
`headers`	`Dict[str, str]`	Normalized header dictionary as returned by :func:`parse_headers`.	required

Returns:

Type	Description
`str`	A tuple `(email, name)` where:
`Optional[str]`	`email` is the sender email address
`Tuple[str, Optional[str]]`	`name` is the display name, or `None` if unavailable

Examples:

"John Doe <john@example.com>" → ("john@example.com", "John Doe") "john@example.com" → ("john@example.com", None)

parse_headers

parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]

Convert a list of Gmail-style headers into a normalized dict.

Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings. This function normalizes them into a case-insensitive dictionary keyed by lowercase header names.

Parameters:

Name	Type	Description	Default
`raw_headers`	`List[Dict[str, str]]`	List of header dictionaries, each containing `name` and `value` keys.	required

Returns:

Type	Description
`Dict[str, str]`	Dictionary mapping lowercase header names to stripped values.

Example

Input: [ {"name": "From", "value": "John Doe john@example.com"}, {"name": "Subject", "value": "Re: Interview Update"}, ]

Output: { "from": "John Doe john@example.com", "subject": "Re: Interview Update", }