Skip to content

# Gmail

## `` mail_intake.adapters.gmail

### Summary

Gmail adapter implementation for Mail Intake.

This module provides a Gmail-specific implementation of the `MailIntakeAdapter` contract.

It is the only place in the codebase where:

- `googleapiclient` is imported.
- Gmail REST API semantics are known.
- Low-level `.execute()` calls are made.

All Gmail-specific behavior must be strictly contained within this module.

### Classes

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