Skip to content

# Reader

## `` mail_intake.ingestion.reader

### Summary

High-level mail ingestion orchestration for Mail Intake.

This module provides the primary, provider-agnostic entry point for reading and processing mail data.

It coordinates:

- Mail adapter access.
- Message and thread iteration.
- Header and body parsing.
- Normalization and model construction.

No provider-specific logic or API semantics are permitted in this layer.

### Classes

#### `` MailIntakeReader

    1

    MailIntakeReader(adapter: MailIntakeAdapter)

High-level read-only ingestion interface.

Notes

Responsibilities:

    1
    2
    3
    4
    5
    6
    7

    - This class is the primary entry point for consumers of the
      Mail Intake library.
    - It orchestrates the full ingestion pipeline:
        - Querying the adapter for message references.
        - Fetching raw provider messages.
        - Parsing and normalizing message data.
        - Constructing domain models.

Constraints:

    1
    2

    - This class is intentionally: Provider-agnostic, stateless beyond
      iteration scope, read-only.

Initialize the mail reader.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`adapter` | `MailIntakeAdapter` | Mail adapter implementation used to retrieve raw messages and threads from a mail provider. | required

##### Functions

###### `` iter_messages

    1

    iter_messages(query: str) -> Iterator[MailIntakeMessage]

Iterate over parsed messages matching a provider query.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`query` | `str` | Provider-specific query string used to filter messages. | required

Yields:

Name | Type | Description
--- | --- | ---
`MailIntakeMessage` | `MailIntakeMessage` | Fully parsed and normalized `MailIntakeMessage` instances.

Raises:

Type | Description
--- | ---
`MailIntakeParsingError` | If a message cannot be parsed.

###### `` iter_threads

    1

    iter_threads(query: str) -> Iterator[MailIntakeThread]

Iterate over threads constructed from messages matching a query.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`query` | `str` | Provider-specific query string used to filter messages. | required

Yields:

Name | Type | Description
--- | --- | ---
`MailIntakeThread` | `MailIntakeThread` | An iterator of `MailIntakeThread` instances.

Raises:

Type | Description
--- | ---
``MailIntakeParsingError`` | If a message cannot be parsed.

Notes

Guarantees:

    1
    2

    - Messages are grouped by `thread_id` and yielded as complete
      thread objects containing all associated messages.

### Functions