Base

mail_intake.adapters.base

Mail provider adapter contracts for Mail Intake.

This module defines the provider-agnostic adapter interface used for read-only mail ingestion.

Adapters encapsulate all provider-specific access logic and expose a minimal, normalized contract to the rest of the system. No provider-specific types or semantics should leak beyond implementations of this interface.

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": "..." }