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:

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

Lifecycle:

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

Functions

fetch_message abstractmethod

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

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

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:

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

Example

Typical yield:

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

MailIntakeGmailAdapter

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:

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

Constraints:

- 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

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

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

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

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.