Reader
mail_intake.ingestion.reader
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.
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. |