Skip to content

# Headers

## `` mail_intake.parsers.headers

### Summary

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.

### Functions

#### `` extract_sender

    1

    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 `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:

    1
    2

    - 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

    1

    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:

    1
    2
    3
    4

    - 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:

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11

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