Adapters

mail_intake.adapters

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 adapters exported from this package are considered the supported integration surface for mail providers.

MailIntakeAdapter

Bases: ABC

Base adapter interface for mail providers.

This interface defines the minimal contract required to: - Discover messages matching a query - Retrieve full message payloads - Retrieve full thread payloads

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

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]	Provider-native message payload
Dict[str, Any]	(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]	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.

Implementations must yield dictionaries containing at least: - message_id: Provider-specific message identifier - thread_id: Provider-specific thread identifier

Parameters:

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

Yields:

Type	Description
Dict[str, str]	Dictionaries containing message and thread identifiers.

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

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

Design 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'

service property

service: Any

Lazily initialize and return the Gmail API service client.

Returns:

Type	Description
Any	Initialized Gmail API service instance.

Raises:

Type	Description
MailIntakeAdapterError	If the Gmail service cannot be initialized.

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]	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]	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]	Dictionaries containing:
Dict[str, str]	message_id: Gmail message ID
Dict[str, str]	thread_id: Gmail thread ID

Raises:

Type	Description
MailIntakeAdapterError	If the Gmail API returns an error.