Skip to content

# Adapters

## `` mail_intake.adapters

### Summary

Mail provider adapter implementations for Mail Intake.

This package contains adapter-layer implementations responsible for interfacing with external mail providers and exposing a normalized, provider-agnostic contract to the rest of the system.

Adapters in this package:

- Implement the `MailIntakeAdapter` interface.
- Encapsulate all provider-specific APIs and semantics.
- Perform read-only access to mail data.
- Return provider-native payloads without interpretation.

Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.

### Public API

- `MailIntakeAdapter`
- `MailIntakeGmailAdapter`

### 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": "..."
    }

#### `` MailIntakeGmailAdapter

    1

    MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider, user_id: str = 'me')

Bases: `MailIntakeAdapter`

Gmail read-only adapter.

This adapter implements the `MailIntakeAdapter` interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.

Notes

Responsibilities:

    1
    2
    3

    - This class is the ONLY place where `googleapiclient` is imported.
    - Gmail REST semantics are known.
    - `.execute()` is called.

Constraints:

    1
    2
    3

    - Must remain thin and imperative.
    - Must not perform parsing or interpretation.
    - Must not expose Gmail-specific types beyond this class.

Initialize the Gmail adapter.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`auth_provider` | `MailIntakeAuthProvider` | Authentication provider capable of supplying valid Gmail API credentials. | required
`user_id` | `str` | Gmail user identifier. Defaults to `"me"`. | `'me'`

##### Attributes

###### `` service `property`

    1

    service: Any

Lazily initialize and return the Gmail API service client.

Returns:

Name | Type | Description
--- | --- | ---
`Any` | `Any` | Initialized Gmail API service instance.

Raises:

Type | Description
--- | ---
`MailIntakeAdapterError` | If the Gmail service cannot be initialized.

##### Functions

###### `` fetch_message

    1

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

Fetch a full Gmail message by message ID.

Parameters:

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

Returns:

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

Raises:

Type | Description
--- | ---
`MailIntakeAdapterError` | If the Gmail API returns an error.

###### `` fetch_thread

    1

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

Fetch a full Gmail thread by thread ID.

Parameters:

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

Returns:

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

Raises:

Type | Description
--- | ---
`MailIntakeAdapterError` | If the Gmail API returns an error.

###### `` iter_message_refs

    1

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

Iterate over message references matching the query.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`query` | `str` | Gmail search query string. | required

Yields:

Type | Description
--- | ---
`Dict[str, str]` | Dict[str, str]: Dictionaries containing `message_id` and `thread_id`.

Raises:

Type | Description
--- | ---
`MailIntakeAdapterError` | If the Gmail API returns an error.