Ingestion
mail_intake.ingestion
Mail ingestion orchestration for Mail Intake.
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.
MailIntakeReader
MailIntakeReader(adapter: MailIntakeAdapter)
High-level read-only ingestion interface.
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
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 |
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:
| Type | Description |
|---|---|
MailIntakeMessage
|
Fully parsed and normalized |
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.
Messages are grouped by thread_id and yielded as complete thread
objects containing all associated messages.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
query |
str
|
Provider-specific query string used to filter messages. |
required |
Returns:
| Type | Description |
|---|---|
Iterator[MailIntakeThread]
|
An iterator of |
Raises:
| Type | Description |
|---|---|
MailIntakeParsingError
|
If a message cannot be parsed. |