Reader

mail_intake.ingestion.reader

High-level mail ingestion orchestration for Mail Intake.

Summary

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

MailIntakeReader(adapter: MailIntakeAdapter)

High-level read-only ingestion interface.

Notes

Responsibilities:

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

- 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

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

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:

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