{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"mail_intake","text":""},{"location":"#mail_intake","title":"mail_intake","text":"

Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.

"},{"location":"#mail_intake--summary","title":"Summary","text":"

Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.

The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

"},{"location":"#mail_intake--installation","title":"Installation","text":"

Install using pip:

pip install mail-intake\n

Or with Poetry:

poetry add mail-intake\n

Mail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).

"},{"location":"#mail_intake--quick-start","title":"Quick start","text":"

Minimal Gmail ingestion example (local development):

from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n    credentials_path=\"credentials.json\",\n    store=store,\n    scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n    print(message.subject, message.from_email)\n

Iterating over threads:

for thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n
"},{"location":"#mail_intake--architecture","title":"Architecture","text":"

Mail Intake is designed to be extensible via public contracts exposed through its modules:

Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.

Design Guarantees: - Read-only access: no mutation of provider state - Provider-agnostic domain models - Explicit configuration and dependency injection - No implicit global state or environment reads - Deterministic, testable behavior - Distributed-safe authentication design

Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.

Core Philosophy: Mail Intake is built as a contract-first ingestion pipeline: 1. Layered Decoupling: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates. 2. Provider Agnosticism: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals. 3. Stateless Workflows: The library functions as a read-only pipe, ensuring side-effect-free ingestion.

"},{"location":"#mail_intake--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

"},{"location":"config/","title":"Config","text":""},{"location":"config/#mail_intake.config","title":"mail_intake.config","text":"

Global configuration models for Mail Intake.

"},{"location":"config/#mail_intake.config--summary","title":"Summary","text":"

This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.

Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.

"},{"location":"config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfig dataclass","text":"
MailIntakeConfig(provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: Optional[str] = ..., token_path: Optional[str] = ...)\n

Global configuration for mail-intake.

Notes

Guarantees:

- This configuration is intentionally explicit and immutable\n- No implicit environment reads or global state\n- Explicit configuration over implicit defaults\n- No direct environment or filesystem access\n- This model is safe to pass across layers and suitable for serialization\n
"},{"location":"config/#mail_intake.config.MailIntakeConfig-attributes","title":"Attributes","text":""},{"location":"config/#mail_intake.config.MailIntakeConfig.credentials_path","title":"credentials_path class-attribute instance-attribute","text":"
credentials_path: Optional[str] = None\n

Optional path to provider credentials configuration.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.provider","title":"provider class-attribute instance-attribute","text":"
provider: str = 'gmail'\n

Identifier of the mail provider to use (e.g., \"gmail\").

"},{"location":"config/#mail_intake.config.MailIntakeConfig.readonly","title":"readonly class-attribute instance-attribute","text":"
readonly: bool = True\n

Whether ingestion should operate in read-only mode.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_path class-attribute instance-attribute","text":"
token_path: Optional[str] = None\n

Optional path to persisted authentication tokens.

"},{"location":"config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_id class-attribute instance-attribute","text":"
user_id: str = 'me'\n

Provider-specific user identifier. Defaults to the authenticated user.

"},{"location":"exceptions/","title":"Exceptions","text":""},{"location":"exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":"

Exception hierarchy for Mail Intake.

"},{"location":"exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"

This module defines the canonical exception types used throughout the Mail Intake library.

All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.

"},{"location":"exceptions/#mail_intake.exceptions-classes","title":"Classes","text":""},{"location":"exceptions/#mail_intake.exceptions.MailIntakeAdapterError","title":"MailIntakeAdapterError","text":"

Bases: MailIntakeError

Errors raised by mail provider adapters.

Notes

Lifecycle:

- Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeAuthError","title":"MailIntakeAuthError","text":"

Bases: MailIntakeError

Authentication and credential-related failures.

Notes

Lifecycle:

- Raised when authentication providers are unable to acquire, refresh, or persist valid credentials\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeError","title":"MailIntakeError","text":"

Bases: Exception

Base exception for all Mail Intake errors.

Notes

Guarantees:

- This is the root of the Mail Intake exception hierarchy\n- All errors raised by the library must derive from this class\n- Consumers should generally catch this type when handling library-level failures\n
"},{"location":"exceptions/#mail_intake.exceptions.MailIntakeParsingError","title":"MailIntakeParsingError","text":"

Bases: MailIntakeError

Errors encountered while parsing message content.

Notes

Lifecycle:

- Raised when raw provider payloads cannot be interpreted or normalized into internal domain models\n
"},{"location":"adapters/","title":"Adapters","text":""},{"location":"adapters/#mail_intake.adapters","title":"mail_intake.adapters","text":"

Mail provider adapter implementations for Mail Intake.

"},{"location":"adapters/#mail_intake.adapters--summary","title":"Summary","text":"

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.

"},{"location":"adapters/#mail_intake.adapters--public-api","title":"Public API","text":"
MailIntakeAdapter\nMailIntakeGmailAdapter\n
"},{"location":"adapters/#mail_intake.adapters-classes","title":"Classes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- discover messages matching a query\n- retrieve full message payloads\n- retrieve full thread payloads\n

Lifecycle:

- adapters are intentionally read-only and must not mutate provider state\n
"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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

"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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``\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider, user_id: str = 'me')\n

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\n- Gmail REST semantics are known\n- .execute() is called\n

Constraints:

- Must remain thin and imperative\n- Must not perform parsing or interpretation\n- Must not expose Gmail-specific types beyond this class\n

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'"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

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.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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.

"},{"location":"adapters/base/","title":"Base","text":""},{"location":"adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":"

Mail provider adapter contracts for Mail Intake.

"},{"location":"adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"

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.

"},{"location":"adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- discover messages matching a query\n- retrieve full message payloads\n- retrieve full thread payloads\n

Lifecycle:

- adapters are intentionally read-only and must not mutate provider state\n
"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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

"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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``\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"adapters/gmail/","title":"Gmail","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail","title":"mail_intake.adapters.gmail","text":"

Gmail adapter implementation for Mail Intake.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail--summary","title":"Summary","text":"

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.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider, user_id: str = 'me')\n

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\n- Gmail REST semantics are known\n- .execute() is called\n

Constraints:

- Must remain thin and imperative\n- Must not perform parsing or interpretation\n- Must not expose Gmail-specific types beyond this class\n

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'"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

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.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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.

"},{"location":"auth/","title":"Auth","text":""},{"location":"auth/#mail_intake.auth","title":"mail_intake.auth","text":"

Authentication provider implementations for Mail Intake.

"},{"location":"auth/#mail_intake.auth--summary","title":"Summary","text":"

This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.

It exposes: - A stable, provider-agnostic authentication contract - Concrete authentication providers for supported platforms

Authentication providers: - Are responsible for credential acquisition and lifecycle management - Are intentionally decoupled from adapter logic - May be extended by users to support additional providers

Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.

"},{"location":"auth/#mail_intake.auth--public-api","title":"Public API","text":"
MailIntakeAuthProvider\nMailIntakeGoogleAuth\n
"},{"location":"auth/#mail_intake.auth-classes","title":"Classes","text":""},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n

Constraints:

- Mail adapters must treat returned credentials as opaque and provider-specific\n- Mail adapters rely only on the declared credential type expected by the adapter\n
"},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design\n- Represents the sole entry point through which adapters obtain authentication material\n- Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception\n
"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n

Guarantees:

- This class is synchronous by design and maintains a minimal internal state\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store\n- Refresh expired credentials when possible\n- Perform an interactive OAuth login as a fallback\n- Persist valid credentials for future use\n
"},{"location":"auth/base/","title":"Base","text":""},{"location":"auth/base/#mail_intake.auth.base","title":"mail_intake.auth.base","text":"

Authentication provider contracts for Mail Intake.

"},{"location":"auth/base/#mail_intake.auth.base--summary","title":"Summary","text":"

This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.

Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.

"},{"location":"auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n

Constraints:

- Mail adapters must treat returned credentials as opaque and provider-specific\n- Mail adapters rely only on the declared credential type expected by the adapter\n
"},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"auth/base/#mail_intake.auth.base.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design\n- Represents the sole entry point through which adapters obtain authentication material\n- Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception\n
"},{"location":"auth/google/","title":"Google","text":""},{"location":"auth/google/#mail_intake.auth.google","title":"mail_intake.auth.google","text":"

Google authentication provider implementation for Mail Intake.

"},{"location":"auth/google/#mail_intake.auth.google--summary","title":"Summary","text":"

This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.

It encapsulates all Google-specific authentication concerns, including: - Credential loading and persistence - Token refresh handling - Interactive OAuth flow initiation - Coordination with a credential persistence layer

No Google authentication details should leak outside this module.

"},{"location":"auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n

Guarantees:

- This class is synchronous by design and maintains a minimal internal state\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store\n- Refresh expired credentials when possible\n- Perform an interactive OAuth login as a fallback\n- Persist valid credentials for future use\n
"},{"location":"credentials/","title":"Credentials","text":""},{"location":"credentials/#mail_intake.credentials","title":"mail_intake.credentials","text":"

Credential persistence interfaces and implementations for Mail Intake.

"},{"location":"credentials/#mail_intake.credentials--summary","title":"Summary","text":"

This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.

The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.

The package provides: - A generic CredentialStore abstraction defining the persistence contract - Local filesystem\u2013based storage for development and single-node use - Distributed, Redis-backed storage for production and scaled deployments

Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.

"},{"location":"credentials/#mail_intake.credentials--public-api","title":"Public API","text":"
CredentialStore\nPickleCredentialStore\nRedisCredentialStore\n
"},{"location":"credentials/#mail_intake.credentials-classes","title":"Classes","text":""},{"location":"credentials/#mail_intake.credentials.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface for authentication credentials.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from storage mechanics\n- Keep implementation focused only on persistence\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored\n    - The serialization format used to persist credentials\n    - The underlying storage backend or durability guarantees\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore.load","title":"load abstractmethod","text":"
load() -> Optional[T]\n

Load previously persisted credentials.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n- The store must not attempt to validate, refresh, or otherwise interpret the returned credentials\n
"},{"location":"credentials/#mail_intake.credentials.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from the local filesystem.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate or interpret the returned credentials\n
"},{"location":"credentials/#mail_intake.credentials.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = None)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval\n- It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n

Guarantees:

- The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n- This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

An initialized Redis client instance (for example, redis.Redis or a compatible interface) used to communicate with the Redis server.

required key str

The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.

required serialize Callable[[T], bytes]

A callable that converts a credential object of type T into a bytes representation suitable for storage in Redis.

required deserialize Callable[[bytes], T]

A callable that converts a bytes payload retrieved from Redis back into a credential object of type T.

required ttl_seconds Optional[int]

Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If None, credentials are stored without an expiration.

None"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from Redis.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable\n
"},{"location":"credentials/#mail_intake.credentials.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"credentials/pickle/","title":"Pickle","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle","title":"mail_intake.credentials.pickle","text":"

Local filesystem\u2013based credential persistence for Mail Intake.

"},{"location":"credentials/pickle/#mail_intake.credentials.pickle--summary","title":"Summary","text":"

This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.

The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.

Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.

"},{"location":"credentials/pickle/#mail_intake.credentials.pickle-classes","title":"Classes","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from the local filesystem.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate or interpret the returned credentials\n
"},{"location":"credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"credentials/redis/","title":"Redis","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis","title":"mail_intake.credentials.redis","text":"

Redis-backed credential persistence for Mail Intake.

"},{"location":"credentials/redis/#mail_intake.credentials.redis--summary","title":"Summary","text":"

This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.

The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.

Key characteristics: - Distributed-safe, shared storage using Redis - Explicit, caller-defined serialization and deserialization - No reliance on unsafe mechanisms such as pickle - Optional time-to-live (TTL) support for automatic credential expiry

This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.

"},{"location":"credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = None)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval\n- It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n

Guarantees:

- The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n- This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

An initialized Redis client instance (for example, redis.Redis or a compatible interface) used to communicate with the Redis server.

required key str

The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.

required serialize Callable[[T], bytes]

A callable that converts a credential object of type T into a bytes representation suitable for storage in Redis.

required deserialize Callable[[bytes], T]

A callable that converts a bytes payload retrieved from Redis back into a credential object of type T.

required ttl_seconds Optional[int]

Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If None, credentials are stored without an expiration.

None"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from Redis.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable\n
"},{"location":"credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"credentials/store/","title":"Store","text":""},{"location":"credentials/store/#mail_intake.credentials.store","title":"mail_intake.credentials.store","text":"

Credential persistence abstractions for Mail Intake.

"},{"location":"credentials/store/#mail_intake.credentials.store--summary","title":"Summary","text":"

This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.

The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.

By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.

"},{"location":"credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface for authentication credentials.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from storage mechanics\n- Keep implementation focused only on persistence\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored\n    - The serialization format used to persist credentials\n    - The underlying storage backend or durability guarantees\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore-functions","title":"Functions","text":""},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.load","title":"load abstractmethod","text":"
load() -> Optional[T]\n

Load previously persisted credentials.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n- The store must not attempt to validate, refresh, or otherwise interpret the returned credentials\n
"},{"location":"credentials/store/#mail_intake.credentials.store.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"ingestion/","title":"Ingestion","text":""},{"location":"ingestion/#mail_intake.ingestion","title":"mail_intake.ingestion","text":"

Mail ingestion orchestration for Mail Intake.

"},{"location":"ingestion/#mail_intake.ingestion--summary","title":"Summary","text":"

This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.

It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.

Components in this package: - Are provider-agnostic - Depend only on adapter and parser contracts - Contain no provider-specific API logic - Expose read-only ingestion workflows

Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.

"},{"location":"ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"
MailIntakeReader\n
"},{"location":"ingestion/#mail_intake.ingestion-classes","title":"Classes","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the Mail Intake library\n- It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeThread MailIntakeThread

An iterator of MailIntakeThread instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages\n
"},{"location":"ingestion/reader/","title":"Reader","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader","title":"mail_intake.ingestion.reader","text":"

High-level mail ingestion orchestration for Mail Intake.

"},{"location":"ingestion/reader/#mail_intake.ingestion.reader--summary","title":"Summary","text":"

This module provides the primary, provider-agnostic entry point for reading and processing mail data.

It coordinates: - Mail adapter access - Message and thread iteration - Header and body parsing - Normalization and model construction

No provider-specific logic or API semantics are permitted in this layer.

"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the Mail Intake library\n- It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeThread MailIntakeThread

An iterator of MailIntakeThread instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages\n
"},{"location":"ingestion/reader/#mail_intake.ingestion.reader-functions","title":"Functions","text":""},{"location":"mail_intake/","title":"Mail Intake","text":""},{"location":"mail_intake/#mail_intake","title":"mail_intake","text":"

Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.

"},{"location":"mail_intake/#mail_intake--summary","title":"Summary","text":"

Mail Intake is a contract-first library designed to ingest, parse, and normalize email data from external providers (such as Gmail) into clean, provider-agnostic domain models.

The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:

The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.

"},{"location":"mail_intake/#mail_intake--installation","title":"Installation","text":"

Install using pip:

pip install mail-intake\n

Or with Poetry:

poetry add mail-intake\n

Mail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).

"},{"location":"mail_intake/#mail_intake--quick-start","title":"Quick start","text":"

Minimal Gmail ingestion example (local development):

from mail_intake.ingestion import MailIntakeReader\nfrom mail_intake.adapters import MailIntakeGmailAdapter\nfrom mail_intake.auth import MailIntakeGoogleAuth\nfrom mail_intake.credentials import PickleCredentialStore\n\nstore = PickleCredentialStore(path=\"token.pickle\")\n\nauth = MailIntakeGoogleAuth(\n    credentials_path=\"credentials.json\",\n    store=store,\n    scopes=[\"https://www.googleapis.com/auth/gmail.readonly\"],\n)\n\nadapter = MailIntakeGmailAdapter(auth_provider=auth)\nreader = MailIntakeReader(adapter)\n\nfor message in reader.iter_messages(\"from:recruiter@example.com\"):\n    print(message.subject, message.from_email)\n

Iterating over threads:

for thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n
"},{"location":"mail_intake/#mail_intake--architecture","title":"Architecture","text":"

Mail Intake is designed to be extensible via public contracts exposed through its modules:

Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.

Design Guarantees: - Read-only access: no mutation of provider state - Provider-agnostic domain models - Explicit configuration and dependency injection - No implicit global state or environment reads - Deterministic, testable behavior - Distributed-safe authentication design

Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.

Core Philosophy: Mail Intake is built as a contract-first ingestion pipeline: 1. Layered Decoupling: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates. 2. Provider Agnosticism: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals. 3. Stateless Workflows: The library functions as a read-only pipe, ensuring side-effect-free ingestion.

"},{"location":"mail_intake/#mail_intake--public-api","title":"Public API","text":"

The supported public API consists of the following top-level modules:

Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.

"},{"location":"mail_intake/config/","title":"Config","text":""},{"location":"mail_intake/config/#mail_intake.config","title":"mail_intake.config","text":"

Global configuration models for Mail Intake.

"},{"location":"mail_intake/config/#mail_intake.config--summary","title":"Summary","text":"

This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.

Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.

"},{"location":"mail_intake/config/#mail_intake.config-classes","title":"Classes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfig dataclass","text":"
MailIntakeConfig(provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: Optional[str] = ..., token_path: Optional[str] = ...)\n

Global configuration for mail-intake.

Notes

Guarantees:

- This configuration is intentionally explicit and immutable\n- No implicit environment reads or global state\n- Explicit configuration over implicit defaults\n- No direct environment or filesystem access\n- This model is safe to pass across layers and suitable for serialization\n
"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig-attributes","title":"Attributes","text":""},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.credentials_path","title":"credentials_path class-attribute instance-attribute","text":"
credentials_path: Optional[str] = None\n

Optional path to provider credentials configuration.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.provider","title":"provider class-attribute instance-attribute","text":"
provider: str = 'gmail'\n

Identifier of the mail provider to use (e.g., \"gmail\").

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.readonly","title":"readonly class-attribute instance-attribute","text":"
readonly: bool = True\n

Whether ingestion should operate in read-only mode.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_path class-attribute instance-attribute","text":"
token_path: Optional[str] = None\n

Optional path to persisted authentication tokens.

"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_id class-attribute instance-attribute","text":"
user_id: str = 'me'\n

Provider-specific user identifier. Defaults to the authenticated user.

"},{"location":"mail_intake/exceptions/","title":"Exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":"

Exception hierarchy for Mail Intake.

"},{"location":"mail_intake/exceptions/#mail_intake.exceptions--summary","title":"Summary","text":"

This module defines the canonical exception types used throughout the Mail Intake library.

All library-raised errors derive from MailIntakeError. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.

"},{"location":"mail_intake/exceptions/#mail_intake.exceptions-classes","title":"Classes","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAdapterError","title":"MailIntakeAdapterError","text":"

Bases: MailIntakeError

Errors raised by mail provider adapters.

Notes

Lifecycle:

- Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAuthError","title":"MailIntakeAuthError","text":"

Bases: MailIntakeError

Authentication and credential-related failures.

Notes

Lifecycle:

- Raised when authentication providers are unable to acquire, refresh, or persist valid credentials\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeError","title":"MailIntakeError","text":"

Bases: Exception

Base exception for all Mail Intake errors.

Notes

Guarantees:

- This is the root of the Mail Intake exception hierarchy\n- All errors raised by the library must derive from this class\n- Consumers should generally catch this type when handling library-level failures\n
"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeParsingError","title":"MailIntakeParsingError","text":"

Bases: MailIntakeError

Errors encountered while parsing message content.

Notes

Lifecycle:

- Raised when raw provider payloads cannot be interpreted or normalized into internal domain models\n
"},{"location":"mail_intake/adapters/","title":"Adapters","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters","title":"mail_intake.adapters","text":"

Mail provider adapter implementations for Mail Intake.

"},{"location":"mail_intake/adapters/#mail_intake.adapters--summary","title":"Summary","text":"

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.

"},{"location":"mail_intake/adapters/#mail_intake.adapters--public-api","title":"Public API","text":"
MailIntakeAdapter\nMailIntakeGmailAdapter\n
"},{"location":"mail_intake/adapters/#mail_intake.adapters-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- discover messages matching a query\n- retrieve full message payloads\n- retrieve full thread payloads\n

Lifecycle:

- adapters are intentionally read-only and must not mutate provider state\n
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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``\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider, user_id: str = 'me')\n

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\n- Gmail REST semantics are known\n- .execute() is called\n

Constraints:

- Must remain thin and imperative\n- Must not perform parsing or interpretation\n- Must not expose Gmail-specific types beyond this class\n

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'"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

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.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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.

"},{"location":"mail_intake/adapters/base/","title":"Base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":"

Mail provider adapter contracts for Mail Intake.

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base--summary","title":"Summary","text":"

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.

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":"

Bases: ABC

Base adapter interface for mail providers.

Notes

Guarantees:

- discover messages matching a query\n- retrieve full message payloads\n- retrieve full thread payloads\n

Lifecycle:

- adapters are intentionally read-only and must not mutate provider state\n
"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_message","title":"fetch_message abstractmethod","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_thread abstractmethod","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs abstractmethod","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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``\n
Example

Typical yield:

{\n    \"message_id\": \"...\",\n    \"thread_id\": \"...\"\n}\n
"},{"location":"mail_intake/adapters/gmail/","title":"Gmail","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail","title":"mail_intake.adapters.gmail","text":"

Gmail adapter implementation for Mail Intake.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail--summary","title":"Summary","text":"

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.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail-classes","title":"Classes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"
MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider, user_id: str = 'me')\n

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\n- Gmail REST semantics are known\n- .execute() is called\n

Constraints:

- Must remain thin and imperative\n- Must not perform parsing or interpretation\n- Must not expose Gmail-specific types beyond this class\n

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'"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-attributes","title":"Attributes","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service property","text":"
service: Any\n

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.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter-functions","title":"Functions","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"
fetch_message(message_id: str) -> Dict[str, Any]\n

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.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"
fetch_thread(thread_id: str) -> Dict[str, Any]\n

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.

"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"
iter_message_refs(query: str) -> Iterator[Dict[str, str]]\n

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.

"},{"location":"mail_intake/auth/","title":"Auth","text":""},{"location":"mail_intake/auth/#mail_intake.auth","title":"mail_intake.auth","text":"

Authentication provider implementations for Mail Intake.

"},{"location":"mail_intake/auth/#mail_intake.auth--summary","title":"Summary","text":"

This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.

It exposes: - A stable, provider-agnostic authentication contract - Concrete authentication providers for supported platforms

Authentication providers: - Are responsible for credential acquisition and lifecycle management - Are intentionally decoupled from adapter logic - May be extended by users to support additional providers

Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.

"},{"location":"mail_intake/auth/#mail_intake.auth--public-api","title":"Public API","text":"
MailIntakeAuthProvider\nMailIntakeGoogleAuth\n
"},{"location":"mail_intake/auth/#mail_intake.auth-classes","title":"Classes","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n

Constraints:

- Mail adapters must treat returned credentials as opaque and provider-specific\n- Mail adapters rely only on the declared credential type expected by the adapter\n
"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design\n- Represents the sole entry point through which adapters obtain authentication material\n- Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception\n
"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n

Guarantees:

- This class is synchronous by design and maintains a minimal internal state\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store\n- Refresh expired credentials when possible\n- Perform an interactive OAuth login as a fallback\n- Persist valid credentials for future use\n
"},{"location":"mail_intake/auth/base/","title":"Base","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base","title":"mail_intake.auth.base","text":"

Authentication provider contracts for Mail Intake.

"},{"location":"mail_intake/auth/base/#mail_intake.auth.base--summary","title":"Summary","text":"

This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.

Authentication concerns are intentionally decoupled from adapter logic. Adapters depend only on this interface and must not be aware of how credentials are acquired, refreshed, or persisted.

"},{"location":"mail_intake/auth/base/#mail_intake.auth.base-classes","title":"Classes","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"

Bases: ABC, Generic[T]

Abstract base class for authentication providers.

This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.

Notes

Responsibilities:

- Acquire credentials from an external provider\n- Refresh or revalidate credentials as needed\n- Handle authentication-specific failure modes\n- Coordinate with credential persistence layers where applicable\n

Constraints:

- Mail adapters must treat returned credentials as opaque and provider-specific\n- Mail adapters rely only on the declared credential type expected by the adapter\n
"},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider-functions","title":"Functions","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider.get_credentials","title":"get_credentials abstractmethod","text":"
get_credentials() -> T\n

Retrieve valid, provider-specific credentials.

Returns:

Name Type Description T T

Credentials of type T suitable for immediate use by the corresponding mail adapter.

Raises:

Type Description Exception

An authentication-specific exception indicating that credentials could not be obtained or validated.

Notes

Guarantees:

- This method is synchronous by design\n- Represents the sole entry point through which adapters obtain authentication material\n- Implementations must either return credentials of the declared type ``T`` that are valid at the time of return or raise an exception\n
"},{"location":"mail_intake/auth/google/","title":"Google","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google","title":"mail_intake.auth.google","text":"

Google authentication provider implementation for Mail Intake.

"},{"location":"mail_intake/auth/google/#mail_intake.auth.google--summary","title":"Summary","text":"

This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.

It encapsulates all Google-specific authentication concerns, including: - Credential loading and persistence - Token refresh handling - Interactive OAuth flow initiation - Coordination with a credential persistence layer

No Google authentication details should leak outside this module.

"},{"location":"mail_intake/auth/google/#mail_intake.auth.google-classes","title":"Classes","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"
MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])\n

Bases: MailIntakeAuthProvider

Google OAuth provider for Gmail access.

This provider implements the MailIntakeAuthProvider interface using Google's OAuth 2.0 flow and credential management libraries.

Notes

Responsibilities:

- Load cached credentials from a credential store when available\n- Refresh expired credentials when possible\n- Initiate an interactive OAuth flow only when required\n- Persist refreshed or newly obtained credentials via the store\n

Guarantees:

- This class is synchronous by design and maintains a minimal internal state\n

Initialize the Google authentication provider.

Parameters:

Name Type Description Default credentials_path str

Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.

required store CredentialStore[Credentials]

Credential store responsible for persisting and retrieving Google OAuth credentials.

required scopes Sequence[str]

OAuth scopes required for Gmail access.

required"},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth-functions","title":"Functions","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"
get_credentials() -> Any\n

Retrieve valid Google OAuth credentials.

Returns:

Name Type Description Credentials Any

A google.oauth2.credentials.Credentials instance suitable for use with Google API clients.

Raises:

Type Description MailIntakeAuthError

If credentials cannot be loaded, refreshed, or obtained via interactive authentication.

Notes

Lifecycle:

- Load cached credentials from the configured credential store\n- Refresh expired credentials when possible\n- Perform an interactive OAuth login as a fallback\n- Persist valid credentials for future use\n
"},{"location":"mail_intake/credentials/","title":"Credentials","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials","title":"mail_intake.credentials","text":"

Credential persistence interfaces and implementations for Mail Intake.

"},{"location":"mail_intake/credentials/#mail_intake.credentials--summary","title":"Summary","text":"

This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.

The credential persistence layer is intentionally decoupled from authentication logic. Authentication providers are responsible for credential acquisition, validation, and refresh, while implementations within this package are responsible solely for storage and retrieval.

The package provides: - A generic CredentialStore abstraction defining the persistence contract - Local filesystem\u2013based storage for development and single-node use - Distributed, Redis-backed storage for production and scaled deployments

Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.

"},{"location":"mail_intake/credentials/#mail_intake.credentials--public-api","title":"Public API","text":"
CredentialStore\nPickleCredentialStore\nRedisCredentialStore\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface for authentication credentials.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from storage mechanics\n- Keep implementation focused only on persistence\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored\n    - The serialization format used to persist credentials\n    - The underlying storage backend or durability guarantees\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.load","title":"load abstractmethod","text":"
load() -> Optional[T]\n

Load previously persisted credentials.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n- The store must not attempt to validate, refresh, or otherwise interpret the returned credentials\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from the local filesystem.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate or interpret the returned credentials\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = None)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval\n- It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n

Guarantees:

- The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n- This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

An initialized Redis client instance (for example, redis.Redis or a compatible interface) used to communicate with the Redis server.

required key str

The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.

required serialize Callable[[T], bytes]

A callable that converts a credential object of type T into a bytes representation suitable for storage in Redis.

required deserialize Callable[[bytes], T]

A callable that converts a bytes payload retrieved from Redis back into a credential object of type T.

required ttl_seconds Optional[int]

Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If None, credentials are stored without an expiration.

None"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from Redis.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable\n
"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"mail_intake/credentials/pickle/","title":"Pickle","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle","title":"mail_intake.credentials.pickle","text":"

Local filesystem\u2013based credential persistence for Mail Intake.

"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle--summary","title":"Summary","text":"

This module provides a file-backed implementation of the CredentialStore abstraction using Python's pickle module.

The pickle-based credential store is intended for local development, single-node deployments, and controlled environments where credentials do not need to be shared across processes or machines.

Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.

"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore","title":"PickleCredentialStore","text":"
PickleCredentialStore(path: str)\n

Bases: CredentialStore[T]

Filesystem-backed credential store using pickle serialization.

This store persists credentials as a pickled object on the local filesystem. It is a simple implementation intended primarily for development, testing, and single-process execution contexts.

Notes

Guarantees:

- Stores credentials on the local filesystem\n- Uses pickle for serialization and deserialization\n- Does not provide encryption, locking, or concurrency guarantees\n

Constraints:

- Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class\n

Initialize a pickle-backed credential store.

Parameters:

Name Type Description Default path str

Filesystem path where credentials will be stored. The file will be created or overwritten as needed.

required"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove persisted credentials from the local filesystem.

Notes

Lifecycle:

- This method deletes the credential file if it exists and should be treated as an idempotent operation\n
"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from the local filesystem.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If the credential file does not exist or cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate or interpret the returned credentials\n
"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to the local filesystem.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials at the configured path are overwritten\n
"},{"location":"mail_intake/credentials/redis/","title":"Redis","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis","title":"mail_intake.credentials.redis","text":"

Redis-backed credential persistence for Mail Intake.

"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis--summary","title":"Summary","text":"

This module provides a Redis-based implementation of the CredentialStore abstraction, enabling credential persistence across distributed and horizontally scaled deployments.

The Redis credential store is designed for environments where authentication credentials must be shared safely across multiple processes, containers, or nodes, such as container orchestration platforms and microservice architectures.

Key characteristics: - Distributed-safe, shared storage using Redis - Explicit, caller-defined serialization and deserialization - No reliance on unsafe mechanisms such as pickle - Optional time-to-live (TTL) support for automatic credential expiry

This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.

"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"
RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = None)\n

Bases: CredentialStore[T]

Redis-backed implementation of CredentialStore.

This store persists credentials in Redis and is suitable for distributed and horizontally scaled deployments where credentials must be shared across multiple processes or nodes.

Notes

Responsibilities:

- This class is responsible only for persistence and retrieval\n- It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored\n

Guarantees:

- The store is intentionally generic and delegates all serialization concerns to caller-provided functions\n- This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited\n

Initialize a Redis-backed credential store.

Parameters:

Name Type Description Default redis_client Any

An initialized Redis client instance (for example, redis.Redis or a compatible interface) used to communicate with the Redis server.

required key str

The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.

required serialize Callable[[T], bytes]

A callable that converts a credential object of type T into a bytes representation suitable for storage in Redis.

required deserialize Callable[[bytes], T]

A callable that converts a bytes payload retrieved from Redis back into a credential object of type T.

required ttl_seconds Optional[int]

Optional time-to-live (TTL) for the stored credentials, expressed in seconds. When provided, Redis will automatically expire the stored credentials after the specified duration. If None, credentials are stored without an expiration.

None"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"
clear() -> None\n

Remove stored credentials from Redis.

Notes

Lifecycle:

- This operation deletes the configured Redis key if it exists\n- Implementations should treat this method as idempotent\n
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.load","title":"load","text":"
load() -> Optional[T]\n

Load credentials from Redis.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are present and successfully deserialized; otherwise None.

Notes

Guarantees:

- If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns ``None``\n- The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable\n
"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.save","title":"save","text":"
save(credentials: T) -> None\n

Persist credentials to Redis.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Responsibilities:

- Any previously stored credentials under the same key are overwritten\n- If a TTL is configured, the credentials will expire automatically after the specified duration\n
"},{"location":"mail_intake/credentials/store/","title":"Store","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store","title":"mail_intake.credentials.store","text":"

Credential persistence abstractions for Mail Intake.

"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store--summary","title":"Summary","text":"

This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.

The CredentialStore abstraction establishes a strict separation between credential lifecycle management and credential storage. Authentication providers are responsible for acquiring, validating, refreshing, and revoking credentials, while concrete store implementations are responsible solely for persistence concerns.

By remaining agnostic to credential structure, serialization format, and storage backend, this module enables multiple persistence strategies\u2014such as local files, in-memory caches, distributed stores, or secrets managers\u2014without coupling authentication logic to any specific storage mechanism.

"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store-classes","title":"Classes","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":"

Bases: ABC, Generic[T]

Abstract base class defining a generic persistence interface for authentication credentials.

Notes

Responsibilities:

- Provide persistent storage separating life-cycle management from storage mechanics\n- Keep implementation focused only on persistence\n

Constraints:

- The store is intentionally agnostic to:\n    - The concrete credential type being stored\n    - The serialization format used to persist credentials\n    - The underlying storage backend or durability guarantees\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore-functions","title":"Functions","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.clear","title":"clear abstractmethod","text":"
clear() -> None\n

Remove any persisted credentials from the store.

Notes

Lifecycle:

- This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable\n- Must ensure that no stale authentication material remains accessible\n

Guarantees:

- Implementations should treat this operation as idempotent\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.load","title":"load abstractmethod","text":"
load() -> Optional[T]\n

Load previously persisted credentials.

Returns:

Type Description Optional[T]

Optional[T]: An instance of type T if credentials are available and loadable; otherwise None.

Notes

Guarantees:

- Implementations should return ``None`` when no credentials are present or when stored credentials cannot be successfully decoded or deserialized\n- The store must not attempt to validate, refresh, or otherwise interpret the returned credentials\n
"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.save","title":"save abstractmethod","text":"
save(credentials: T) -> None\n

Persist credentials to the underlying storage backend.

Parameters:

Name Type Description Default credentials T

The credential object to persist.

required Notes

Lifecycle:

- This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence\n

Responsibilities:

- Ensuring durability appropriate to the deployment context\n- Applying encryption or access controls where required\n- Overwriting any previously stored credentials\n
"},{"location":"mail_intake/ingestion/","title":"Ingestion","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion","title":"mail_intake.ingestion","text":"

Mail ingestion orchestration for Mail Intake.

"},{"location":"mail_intake/ingestion/#mail_intake.ingestion--summary","title":"Summary","text":"

This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.

It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.

Components in this package: - Are provider-agnostic - Depend only on adapter and parser contracts - Contain no provider-specific API logic - Expose read-only ingestion workflows

Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.

"},{"location":"mail_intake/ingestion/#mail_intake.ingestion--public-api","title":"Public API","text":"
MailIntakeReader\n
"},{"location":"mail_intake/ingestion/#mail_intake.ingestion-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the Mail Intake library\n- It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeThread MailIntakeThread

An iterator of MailIntakeThread instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages\n
"},{"location":"mail_intake/ingestion/reader/","title":"Reader","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader","title":"mail_intake.ingestion.reader","text":"

High-level mail ingestion orchestration for Mail Intake.

"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader--summary","title":"Summary","text":"

This module provides the primary, provider-agnostic entry point for reading and processing mail data.

It coordinates: - Mail adapter access - Message and thread iteration - Header and body parsing - Normalization and model construction

No provider-specific logic or API semantics are permitted in this layer.

"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-classes","title":"Classes","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"
MailIntakeReader(adapter: MailIntakeAdapter)\n

High-level read-only ingestion interface.

Notes

Responsibilities:

- This class is the primary entry point for consumers of the Mail Intake library\n- It orchestrates the full ingestion pipeline: Querying the adapter for message references, fetching raw provider messages, parsing and normalizing message data, constructing domain models\n

Constraints:

- This class is intentionally: Provider-agnostic, stateless beyond iteration scope, read-only\n

Initialize the mail reader.

Parameters:

Name Type Description Default adapter MailIntakeAdapter

Mail adapter implementation used to retrieve raw messages and threads from a mail provider.

required"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader-functions","title":"Functions","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"
iter_messages(query: str) -> Iterator[MailIntakeMessage]\n

Iterate over parsed messages matching a provider query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeMessage MailIntakeMessage

Fully parsed and normalized MailIntakeMessage instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"
iter_threads(query: str) -> Iterator[MailIntakeThread]\n

Iterate over threads constructed from messages matching a query.

Parameters:

Name Type Description Default query str

Provider-specific query string used to filter messages.

required

Yields:

Name Type Description MailIntakeThread MailIntakeThread

An iterator of MailIntakeThread instances.

Raises:

Type Description MailIntakeParsingError

If a message cannot be parsed.

Notes

Guarantees:

- Messages are grouped by `thread_id` and yielded as complete thread objects containing all associated messages\n
"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader-functions","title":"Functions","text":""},{"location":"mail_intake/models/","title":"Models","text":""},{"location":"mail_intake/models/#mail_intake.models","title":"mail_intake.models","text":"

Domain models for Mail Intake.

"},{"location":"mail_intake/models/#mail_intake.models--summary","title":"Summary","text":"

This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.

Models in this package: - Represent fully parsed and normalized mail data - Are safe to persist, serialize, and index - Contain no provider-specific payloads or API semantics - Serve as stable inputs for downstream processing and analysis

These models form the core internal data contract of the library.

"},{"location":"mail_intake/models/#mail_intake.models--public-api","title":"Public API","text":"
MailIntakeMessage\nMailIntakeThread\n
"},{"location":"mail_intake/models/#mail_intake.models-classes","title":"Classes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str])\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message\n- It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics should appear in this model\n
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: Optional[str]\n

Optional human-readable sender name.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: Dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject and participant set\n- It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n- This model is provider-agnostic and safe to persist\n
"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: Optional[datetime] = None\n

Timestamp of the most recent message in the thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: List[MailIntakeMessage] = field(default_factory=list)\n

Ordered list of messages belonging to this thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: Set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n
"},{"location":"mail_intake/models/message/","title":"Message","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message","title":"mail_intake.models.message","text":"

Message domain models for Mail Intake.

"},{"location":"mail_intake/models/message/#mail_intake.models.message--summary","title":"Summary","text":"

This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.

Models in this module are safe to persist and must not contain any provider-specific fields or semantics.

"},{"location":"mail_intake/models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str])\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message\n- It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics should appear in this model\n
"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: Optional[str]\n

Optional human-readable sender name.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: Dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"mail_intake/models/thread/","title":"Thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":"

Thread domain models for Mail Intake.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"

This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.

Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject and participant set\n- It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n- This model is provider-agnostic and safe to persist\n
"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: Optional[datetime] = None\n

Timestamp of the most recent message in the thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: List[MailIntakeMessage] = field(default_factory=list)\n

Ordered list of messages belonging to this thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: Set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n
"},{"location":"mail_intake/parsers/","title":"Parsers","text":""},{"location":"mail_intake/parsers/#mail_intake.parsers","title":"mail_intake.parsers","text":"

Message parsing utilities for Mail Intake.

"},{"location":"mail_intake/parsers/#mail_intake.parsers--summary","title":"Summary","text":"

This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.

Parsers in this package are responsible for: - Interpreting provider-native message structures - Extracting meaningful fields such as headers, body text, and subjects - Normalizing data into consistent internal representations

This package does not: - Perform network or IO operations - Contain provider API logic - Construct domain models directly

Parsing functions are designed to be composable and are orchestrated by the ingestion layer.

"},{"location":"mail_intake/parsers/#mail_intake.parsers--public-api","title":"Public API","text":"
extract_body\nparse_headers\nextract_sender\nnormalize_subject\n
"},{"location":"mail_intake/parsers/#mail_intake.parsers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_body","title":"extract_body","text":"
extract_body(payload: Dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority: 1. text/plain 2. text/html (stripped to text) 3. Single-part body 4. empty string (if nothing usable found)

Parameters:

Name Type Description Default payload Dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Type Description str

Extracted plain-text message body.

"},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"
extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers Dict[str, str]

Normalized header dictionary as returned by :func:parse_headers.

required

Returns:

Type Description Tuple[str, Optional[str]]

Tuple[str, Optional[str]]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n
Example

Typical values:

``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n``\"john@example.com\"`` -> ``(\"john@example.com\", None)``\n
"},{"location":"mail_intake/parsers/#mail_intake.parsers.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n- Repeats prefix stripping to handle stacked prefixes\n- Collapses excessive whitespace\n- Preserves original casing (no lowercasing)\n

Guarantees:

- This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject\n
"},{"location":"mail_intake/parsers/#mail_intake.parsers.parse_headers","title":"parse_headers","text":"
parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers List[Dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description Dict[str, str]

Dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n- This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"mail_intake/parsers/body/","title":"Body","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body","title":"mail_intake.parsers.body","text":"

Message body extraction utilities for Mail Intake.

This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.

The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.

"},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"
extract_body(payload: Dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority: 1. text/plain 2. text/html (stripped to text) 3. Single-part body 4. empty string (if nothing usable found)

Parameters:

Name Type Description Default payload Dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Type Description str

Extracted plain-text message body.

"},{"location":"mail_intake/parsers/headers/","title":"Headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":"

Message header parsing utilities for Mail Intake.

"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"

This module provides helper functions for normalizing and extracting useful information from provider-native message headers.

The functions here are intentionally simple and tolerant of malformed or incomplete header data.

"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"
extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers Dict[str, str]

Normalized header dictionary as returned by :func:parse_headers.

required

Returns:

Type Description Tuple[str, Optional[str]]

Tuple[str, Optional[str]]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n
Example

Typical values:

``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n``\"john@example.com\"`` -> ``(\"john@example.com\", None)``\n
"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.parse_headers","title":"parse_headers","text":"
parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers List[Dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description Dict[str, str]

Dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n- This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"mail_intake/parsers/subject/","title":"Subject","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject","title":"mail_intake.parsers.subject","text":"

Subject line normalization utilities for Mail Intake.

"},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject--summary","title":"Summary","text":"

This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.

Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.

"},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n- Repeats prefix stripping to handle stacked prefixes\n- Collapses excessive whitespace\n- Preserves original casing (no lowercasing)\n

Guarantees:

- This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject\n
"},{"location":"models/","title":"Models","text":""},{"location":"models/#mail_intake.models","title":"mail_intake.models","text":"

Domain models for Mail Intake.

"},{"location":"models/#mail_intake.models--summary","title":"Summary","text":"

This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.

Models in this package: - Represent fully parsed and normalized mail data - Are safe to persist, serialize, and index - Contain no provider-specific payloads or API semantics - Serve as stable inputs for downstream processing and analysis

These models form the core internal data contract of the library.

"},{"location":"models/#mail_intake.models--public-api","title":"Public API","text":"
MailIntakeMessage\nMailIntakeThread\n
"},{"location":"models/#mail_intake.models-classes","title":"Classes","text":""},{"location":"models/#mail_intake.models.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str])\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message\n- It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics should appear in this model\n
"},{"location":"models/#mail_intake.models.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"models/#mail_intake.models.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: Optional[str]\n

Optional human-readable sender name.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: Dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject and participant set\n- It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n- This model is provider-agnostic and safe to persist\n
"},{"location":"models/#mail_intake.models.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: Optional[datetime] = None\n

Timestamp of the most recent message in the thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: List[MailIntakeMessage] = field(default_factory=list)\n

Ordered list of messages belonging to this thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"models/#mail_intake.models.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: Set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"models/#mail_intake.models.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n
"},{"location":"models/message/","title":"Message","text":""},{"location":"models/message/#mail_intake.models.message","title":"mail_intake.models.message","text":"

Message domain models for Mail Intake.

"},{"location":"models/message/#mail_intake.models.message--summary","title":"Summary","text":"

This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.

Models in this module are safe to persist and must not contain any provider-specific fields or semantics.

"},{"location":"models/message/#mail_intake.models.message-classes","title":"Classes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessage dataclass","text":"
MailIntakeMessage(message_id: str, thread_id: str, timestamp: datetime, from_email: str, from_name: Optional[str], subject: str, body_text: str, snippet: str, raw_headers: Dict[str, str])\n

Canonical internal representation of a single email message.

Notes

Guarantees:

- This model represents a fully parsed and normalized email message\n- It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing\n

Constraints:

- No provider-specific identifiers, payloads, or API semantics should appear in this model\n
"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage-attributes","title":"Attributes","text":""},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.body_text","title":"body_text instance-attribute","text":"
body_text: str\n

Extracted plain-text body content of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_email instance-attribute","text":"
from_email: str\n

Sender email address.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_name instance-attribute","text":"
from_name: Optional[str]\n

Optional human-readable sender name.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_id instance-attribute","text":"
message_id: str\n

Provider-specific message identifier.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headers instance-attribute","text":"
raw_headers: Dict[str, str]\n

Normalized mapping of message headers (header name \u2192 value).

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippet instance-attribute","text":"
snippet: str\n

Short provider-supplied preview snippet of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subject instance-attribute","text":"
subject: str\n

Raw subject line of the message.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier to which this message belongs.

"},{"location":"models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestamp instance-attribute","text":"
timestamp: datetime\n

Message timestamp as a timezone-naive UTC datetime.

"},{"location":"models/thread/","title":"Thread","text":""},{"location":"models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":"

Thread domain models for Mail Intake.

"},{"location":"models/thread/#mail_intake.models.thread--summary","title":"Summary","text":"

This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.

Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.

"},{"location":"models/thread/#mail_intake.models.thread-classes","title":"Classes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThread dataclass","text":"
MailIntakeThread(thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...)\n

Canonical internal representation of an email thread.

Notes

Guarantees:

- A thread groups multiple related messages under a single subject and participant set\n- It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions\n- This model is provider-agnostic and safe to persist\n
"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-attributes","title":"Attributes","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.last_activity_at","title":"last_activity_at class-attribute instance-attribute","text":"
last_activity_at: Optional[datetime] = None\n

Timestamp of the most recent message in the thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messages class-attribute instance-attribute","text":"
messages: List[MailIntakeMessage] = field(default_factory=list)\n

Ordered list of messages belonging to this thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subject instance-attribute","text":"
normalized_subject: str\n

Normalized subject line used to group related messages.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participants class-attribute instance-attribute","text":"
participants: Set[str] = field(default_factory=set)\n

Set of unique participant email addresses observed in the thread.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_id instance-attribute","text":"
thread_id: str\n

Provider-specific thread identifier.

"},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread-functions","title":"Functions","text":""},{"location":"models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"
add_message(message: MailIntakeMessage) -> None\n

Add a message to the thread and update derived fields.

Parameters:

Name Type Description Default message MailIntakeMessage

Parsed mail message to add to the thread.

required Notes

Responsibilities:

- Appends the message to the thread\n- Tracks unique participants\n- Updates the last activity timestamp\n
"},{"location":"parsers/","title":"Parsers","text":""},{"location":"parsers/#mail_intake.parsers","title":"mail_intake.parsers","text":"

Message parsing utilities for Mail Intake.

"},{"location":"parsers/#mail_intake.parsers--summary","title":"Summary","text":"

This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.

Parsers in this package are responsible for: - Interpreting provider-native message structures - Extracting meaningful fields such as headers, body text, and subjects - Normalizing data into consistent internal representations

This package does not: - Perform network or IO operations - Contain provider API logic - Construct domain models directly

Parsing functions are designed to be composable and are orchestrated by the ingestion layer.

"},{"location":"parsers/#mail_intake.parsers--public-api","title":"Public API","text":"
extract_body\nparse_headers\nextract_sender\nnormalize_subject\n
"},{"location":"parsers/#mail_intake.parsers-functions","title":"Functions","text":""},{"location":"parsers/#mail_intake.parsers.extract_body","title":"extract_body","text":"
extract_body(payload: Dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority: 1. text/plain 2. text/html (stripped to text) 3. Single-part body 4. empty string (if nothing usable found)

Parameters:

Name Type Description Default payload Dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Type Description str

Extracted plain-text message body.

"},{"location":"parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"
extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers Dict[str, str]

Normalized header dictionary as returned by :func:parse_headers.

required

Returns:

Type Description Tuple[str, Optional[str]]

Tuple[str, Optional[str]]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n
Example

Typical values:

``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n``\"john@example.com\"`` -> ``(\"john@example.com\", None)``\n
"},{"location":"parsers/#mail_intake.parsers.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n- Repeats prefix stripping to handle stacked prefixes\n- Collapses excessive whitespace\n- Preserves original casing (no lowercasing)\n

Guarantees:

- This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject\n
"},{"location":"parsers/#mail_intake.parsers.parse_headers","title":"parse_headers","text":"
parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers List[Dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description Dict[str, str]

Dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n- This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"parsers/body/","title":"Body","text":""},{"location":"parsers/body/#mail_intake.parsers.body","title":"mail_intake.parsers.body","text":"

Message body extraction utilities for Mail Intake.

This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.

The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.

"},{"location":"parsers/body/#mail_intake.parsers.body-classes","title":"Classes","text":""},{"location":"parsers/body/#mail_intake.parsers.body-functions","title":"Functions","text":""},{"location":"parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"
extract_body(payload: Dict[str, Any]) -> str\n

Extract the best-effort message body from a Gmail payload.

Priority: 1. text/plain 2. text/html (stripped to text) 3. Single-part body 4. empty string (if nothing usable found)

Parameters:

Name Type Description Default payload Dict[str, Any]

Provider-native message payload dictionary.

required

Returns:

Type Description str

Extracted plain-text message body.

"},{"location":"parsers/headers/","title":"Headers","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":"

Message header parsing utilities for Mail Intake.

"},{"location":"parsers/headers/#mail_intake.parsers.headers--summary","title":"Summary","text":"

This module provides helper functions for normalizing and extracting useful information from provider-native message headers.

The functions here are intentionally simple and tolerant of malformed or incomplete header data.

"},{"location":"parsers/headers/#mail_intake.parsers.headers-functions","title":"Functions","text":""},{"location":"parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"
extract_sender(headers: Dict[str, str]) -> Tuple[str, Optional[str]]\n

Extract sender email and optional display name from headers.

Parameters:

Name Type Description Default headers Dict[str, str]

Normalized header dictionary as returned by :func:parse_headers.

required

Returns:

Type Description Tuple[str, Optional[str]]

Tuple[str, Optional[str]]: A tuple (email, name) where email is the sender email address and name is the display name, or None if unavailable.

Notes

Responsibilities:

- This function parses the ``From`` header and attempts to extract sender email address and optional human-readable display name\n
Example

Typical values:

``\"John Doe <john@example.com>\"`` -> ``(\"john@example.com\", \"John Doe\")``\n``\"john@example.com\"`` -> ``(\"john@example.com\", None)``\n
"},{"location":"parsers/headers/#mail_intake.parsers.headers.parse_headers","title":"parse_headers","text":"
parse_headers(raw_headers: List[Dict[str, str]]) -> Dict[str, str]\n

Convert a list of Gmail-style headers into a normalized dict.

Parameters:

Name Type Description Default raw_headers List[Dict[str, str]]

List of header dictionaries, each containing name and value keys.

required

Returns:

Type Description Dict[str, str]

Dict[str, str]: Dictionary mapping lowercase header names to stripped values.

Notes

Guarantees:

- Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings\n- This function normalizes them into a case-insensitive dictionary keyed by lowercase header names\n
Example

Typical usage:

Input:\n    [\n        {\"name\": \"From\", \"value\": \"John Doe <john@example.com>\"},\n        {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},\n    ]\n\nOutput:\n    {\n        \"from\": \"John Doe <john@example.com>\",\n        \"subject\": \"Re: Interview Update\",\n    }\n
"},{"location":"parsers/subject/","title":"Subject","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject","title":"mail_intake.parsers.subject","text":"

Subject line normalization utilities for Mail Intake.

"},{"location":"parsers/subject/#mail_intake.parsers.subject--summary","title":"Summary","text":"

This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.

Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.

"},{"location":"parsers/subject/#mail_intake.parsers.subject-functions","title":"Functions","text":""},{"location":"parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"
normalize_subject(subject: str) -> str\n

Normalize an email subject for thread-level comparison.

Parameters:

Name Type Description Default subject str

Raw subject line from a message header.

required

Returns:

Name Type Description str str

Normalized subject string suitable for thread grouping.

Notes

Responsibilities:

- Strips common prefixes such as ``Re:``, ``Fwd:``, and ``FW:``\n- Repeats prefix stripping to handle stacked prefixes\n- Collapses excessive whitespace\n- Preserves original casing (no lowercasing)\n

Guarantees:

- This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject\n
"}]}