Gmail

mail_intake.adapters.gmail

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.

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.