Gmail

mail_intake.adapters.gmail

Gmail adapter implementation for Mail Intake.

---

Summary

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

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.