Skip to content

# Base

## `` mail_intake.adapters.base

### Summary

Mail provider adapter contracts for Mail Intake.

This module defines the provider-agnostic adapter interface used for read-only mail ingestion.

Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.

### Classes

#### `` MailIntakeAdapter

Bases: `ABC`

Base adapter interface for mail providers.

Notes

Guarantees:

    1
    2
    3

    - Discover messages matching a query.
    - Retrieve full message payloads.
    - Retrieve full thread payloads.

Lifecycle:

    1

    - Adapters are intentionally read-only and must not mutate provider state.

##### Functions

###### `` fetch_message `abstractmethod`

    1

    fetch_message(message_id: str) -> Dict[str, Any]

Fetch a full raw message by message identifier.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`message_id` | `str` | Provider-specific message identifier. | required

Returns:

Type | Description
--- | ---
`Dict[str, Any]` | Dict[str, Any]: Provider-native message payload (e.g., Gmail message JSON structure).

###### `` fetch_thread `abstractmethod`

    1

    fetch_thread(thread_id: str) -> Dict[str, Any]

Fetch a full raw thread by thread identifier.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`thread_id` | `str` | Provider-specific thread identifier. | required

Returns:

Type | Description
--- | ---
`Dict[str, Any]` | Dict[str, Any]: Provider-native thread payload.

###### `` iter_message_refs `abstractmethod`

    1

    iter_message_refs(query: str) -> Iterator[Dict[str, str]]

Iterate over lightweight message references matching a query.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`query` | `str` | Provider-specific query string used to filter messages. | required

Yields:

Type | Description
--- | ---
`Dict[str, str]` | Dict[str, str]: Dictionaries containing message and thread identifiers.

Notes

Guarantees:

    1
    2

    - Implementations must yield dictionaries containing at least
      `message_id` and `thread_id`.

Example

Typical yield:

    1
    2
    3
    4

    {
        "message_id": "...",
        "thread_id": "..."
    }