Skip to content

# Ingestion

## `` mail_intake.ingestion

### Summary

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.

### Public API

- `MailIntakeReader`

### 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.