Base

mail_intake.adapters.base

Mail provider adapter contracts for Mail Intake.

---

Summary

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.

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