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