Headers

mail_intake.parsers.headers

Message header parsing utilities for Mail Intake.

---

Summary

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.

Functions

extract_sender

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

Extract sender email and optional display name from headers.

Parameters:

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

Returns:

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

Notes

Responsibilities:

- This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name

Example

Typical values:

``"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.

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]	Dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- 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

Example

Typical usage:

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",
    }