Ingestion

mail_intake.ingestion

Mail ingestion orchestration for Mail Intake.

Summary

This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.

It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.

Components in this package: - Are provider-agnostic - Depend only on adapter and parser contracts - Contain no provider-specific API logic - Expose read-only ingestion workflows

Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.

Public API

1	`MailIntakeReader`

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