docs/libs/mail-intake/site/search/search_index.json

{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"mail_intake/","title":"Mail Intake","text":""},{"location":"mail_intake/#mail_intake","title":"mail_intake","text":"<p>Mail Intake \u2014 provider-agnostic, read-only email ingestion framework.</p> <p>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.</p> <p>The library is intentionally structured around clear layers, each exposed as a first-class module at the package root:</p> <ul> <li>adapters: provider-specific access (e.g. Gmail)</li> <li>auth: authentication providers and credential lifecycle management</li> <li>credentials: credential persistence abstractions and implementations</li> <li>parsers: extraction and normalization of message content</li> <li>ingestion: orchestration and high-level ingestion workflows</li> <li>models: canonical, provider-agnostic data representations</li> <li>config: explicit global configuration</li> <li>exceptions: library-defined error hierarchy</li> </ul> <p>The package root acts as a namespace, not a facade. Consumers are expected to import functionality explicitly from the appropriate module.</p>"},{"location":"mail_intake/#mail_intake--installation","title":"Installation","text":"<p>Install using pip:</p> <pre><code>pip install mail-intake\n</code></pre> <p>Or with Poetry:</p> <pre><code>poetry add mail-intake\n</code></pre> <p>Mail Intake is pure Python and has no runtime dependencies beyond those required by the selected provider (for example, Google APIs for Gmail).</p>"},{"location":"mail_intake/#mail_intake--basic-usage","title":"Basic Usage","text":"<p>Minimal Gmail ingestion example (local development):</p> <pre><code>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</code></pre> <p>Iterating over threads:</p> <pre><code>for thread in reader.iter_threads(\"subject:Interview\"):\n    print(thread.normalized_subject, len(thread.messages))\n</code></pre>"},{"location":"mail_intake/#mail_intake--extensibility-model","title":"Extensibility Model","text":"<p>Mail Intake is designed to be extensible via public contracts exposed through its modules:</p> <ul> <li>Users MAY implement their own mail adapters by subclassing   <code>adapters.MailIntakeAdapter</code></li> <li>Users MAY implement their own authentication providers by subclassing   <code>auth.MailIntakeAuthProvider[T]</code></li> <li>Users MAY implement their own credential persistence layers by   implementing <code>credentials.CredentialStore[T]</code></li> </ul> <p>Users SHOULD NOT subclass built-in adapter implementations. Built-in adapters (such as Gmail) are reference implementations and may change internally without notice.</p>"},{"location":"mail_intake/#mail_intake--public-api-surface","title":"Public API Surface","text":"<p>The supported public API consists of the following top-level modules:</p> <ul> <li>mail_intake.ingestion</li> <li>mail_intake.adapters</li> <li>mail_intake.auth</li> <li>mail_intake.credentials</li> <li>mail_intake.parsers</li> <li>mail_intake.models</li> <li>mail_intake.config</li> <li>mail_intake.exceptions</li> </ul> <p>Classes and functions should be imported explicitly from these modules. No individual symbols are re-exported at the package root.</p>"},{"location":"mail_intake/#mail_intake--design-guarantees","title":"Design Guarantees","text":"<ul> <li>Read-only access: no mutation of provider state</li> <li>Provider-agnostic domain models</li> <li>Explicit configuration and dependency injection</li> <li>No implicit global state or environment reads</li> <li>Deterministic, testable behavior</li> <li>Distributed-safe authentication design</li> </ul> <p>Mail Intake favors correctness, clarity, and explicitness over convenience shortcuts.</p>"},{"location":"mail_intake/#mail_intake--core-philosophy","title":"Core Philosophy","text":"<p><code>Mail Intake</code> is built as a contract-first ingestion pipeline:</p> <ol> <li>Layered Decoupling: Adapters handle transport, Parsers handle format normalization, and Ingestion orchestrates.</li> <li>Provider Agnosticism: Domain models and core logic never depend on provider-specific (e.g., Gmail) API internals.</li> <li>Stateless Workflows: The library functions as a read-only pipe, ensuring side-effect-free ingestion.</li> </ol>"},{"location":"mail_intake/#mail_intake--documentation-design","title":"Documentation Design","text":"<p>Follow these \"AI-Native\" docstring principles across the codebase:</p>"},{"location":"mail_intake/#mail_intake--for-humans","title":"For Humans","text":"<ul> <li>Namespace Clarity: Always specify which module a class or function belongs to.</li> <li>Contract Explanations: Use the <code>adapters</code> and <code>auth</code> base classes to explain extension requirements.</li> </ul>"},{"location":"mail_intake/#mail_intake--for-llms","title":"For LLMs","text":"<ul> <li>Dotted Paths: Use full dotted paths in docstrings to help agents link concepts across modules.</li> <li>Typed Interfaces: Provide <code>.pyi</code> stubs for every public module to ensure perfect context for AI coding tools.</li> <li>Canonical Exceptions: Always use <code>: description</code> pairs in <code>Raises</code> blocks to enable structured error analysis.</li> </ul>"},{"location":"mail_intake/config/","title":"Config","text":""},{"location":"mail_intake/config/#mail_intake.config","title":"mail_intake.config","text":"<p>Global configuration models for Mail Intake.</p> <p>This module defines the top-level configuration object used to control mail ingestion behavior across adapters, authentication providers, and ingestion workflows.</p> <p>Configuration is intentionally explicit, immutable, and free of implicit environment reads to ensure predictability and testability.</p>"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig","title":"MailIntakeConfig  <code>dataclass</code>","text":"<pre><code>MailIntakeConfig(provider: str = ..., user_id: str = ..., readonly: bool = ..., credentials_path: Optional[str] = ..., token_path: Optional[str] = ...)\n</code></pre> <p>Global configuration for mail-intake.</p> <p>This configuration is intentionally explicit and immutable. No implicit environment reads or global state.</p> <p>Design principles: - Immutable once constructed - Explicit configuration over implicit defaults - No direct environment or filesystem access</p> <p>This model is safe to pass across layers and suitable for serialization.</p>"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.credentials_path","title":"credentials_path  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>credentials_path: Optional[str] = None\n</code></pre> <p>Optional path to provider credentials configuration.</p>"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.provider","title":"provider  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>provider: str = 'gmail'\n</code></pre> <p>Identifier of the mail provider to use (e.g., <code>\"gmail\"</code>).</p>"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.readonly","title":"readonly  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>readonly: bool = True\n</code></pre> <p>Whether ingestion should operate in read-only mode.</p>"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.token_path","title":"token_path  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>token_path: Optional[str] = None\n</code></pre> <p>Optional path to persisted authentication tokens.</p>"},{"location":"mail_intake/config/#mail_intake.config.MailIntakeConfig.user_id","title":"user_id  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>user_id: str = 'me'\n</code></pre> <p>Provider-specific user identifier. Defaults to the authenticated user.</p>"},{"location":"mail_intake/exceptions/","title":"Exceptions","text":""},{"location":"mail_intake/exceptions/#mail_intake.exceptions","title":"mail_intake.exceptions","text":"<p>Exception hierarchy for Mail Intake.</p> <p>This module defines the canonical exception types used throughout the Mail Intake library.</p> <p>All library-raised errors derive from <code>MailIntakeError</code>. Consumers are encouraged to catch this base type (or specific subclasses) rather than provider-specific or third-party exceptions.</p>"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAdapterError","title":"MailIntakeAdapterError","text":"<p>               Bases: <code>MailIntakeError</code></p> <p>Errors raised by mail provider adapters.</p> <p>Raised when a provider adapter encounters API errors, transport failures, or invalid provider responses.</p>"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeAuthError","title":"MailIntakeAuthError","text":"<p>               Bases: <code>MailIntakeError</code></p> <p>Authentication and credential-related failures.</p> <p>Raised when authentication providers are unable to acquire, refresh, or persist valid credentials.</p>"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeError","title":"MailIntakeError","text":"<p>               Bases: <code>Exception</code></p> <p>Base exception for all Mail Intake errors.</p> <p>This is the root of the Mail Intake exception hierarchy. All errors raised by the library must derive from this class.</p> <p>Consumers should generally catch this type when handling library-level failures.</p>"},{"location":"mail_intake/exceptions/#mail_intake.exceptions.MailIntakeParsingError","title":"MailIntakeParsingError","text":"<p>               Bases: <code>MailIntakeError</code></p> <p>Errors encountered while parsing message content.</p> <p>Raised when raw provider payloads cannot be interpreted or normalized into internal domain models.</p>"},{"location":"mail_intake/adapters/","title":"Adapters","text":""},{"location":"mail_intake/adapters/#mail_intake.adapters","title":"mail_intake.adapters","text":"<p>Mail provider adapter implementations for Mail Intake.</p> <p>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.</p> <p>Adapters in this package: - Implement the <code>MailIntakeAdapter</code> interface - Encapsulate all provider-specific APIs and semantics - Perform read-only access to mail data - Return provider-native payloads without interpretation</p> <p>Provider-specific logic must not leak outside of adapter implementations. All parsings, normalizations, and transformations must be handled by downstream components.</p> <p>Public adapters exported from this package are considered the supported integration surface for mail providers.</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter","title":"MailIntakeAdapter","text":"<p>               Bases: <code>ABC</code></p> <p>Base adapter interface for mail providers.</p> <p>This interface defines the minimal contract required to: - Discover messages matching a query - Retrieve full message payloads - Retrieve full thread payloads</p> <p>Adapters are intentionally read-only and must not mutate provider state.</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_message","title":"fetch_message  <code>abstractmethod</code>","text":"<pre><code>fetch_message(message_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full raw message by message identifier.</p> <p>Parameters:</p> Name Type Description Default <code>message_id</code> <code>str</code> <p>Provider-specific message identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native message payload</p> <code>Dict[str, Any]</code> <p>(e.g., Gmail message JSON structure).</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.fetch_thread","title":"fetch_thread  <code>abstractmethod</code>","text":"<pre><code>fetch_thread(thread_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full raw thread by thread identifier.</p> <p>Parameters:</p> Name Type Description Default <code>thread_id</code> <code>str</code> <p>Provider-specific thread identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native thread payload.</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs  <code>abstractmethod</code>","text":"<pre><code>iter_message_refs(query: str) -&gt; Iterator[Dict[str, str]]\n</code></pre> <p>Iterate over lightweight message references matching a query.</p> <p>Implementations must yield dictionaries containing at least: - <code>message_id</code>: Provider-specific message identifier - <code>thread_id</code>: Provider-specific thread identifier</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Provider-specific query string used to filter messages.</p> required <p>Yields:</p> Type Description <code>Dict[str, str]</code> <p>Dictionaries containing message and thread identifiers.</p> Example yield <p>{     \"message_id\": \"...\",     \"thread_id\": \"...\" }</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"<pre><code>MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider, user_id: str = 'me')\n</code></pre> <p>               Bases: <code>MailIntakeAdapter</code></p> <p>Gmail read-only adapter.</p> <p>This adapter implements the <code>MailIntakeAdapter</code> interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.</p> <p>This class is the ONLY place where: - googleapiclient is imported - Gmail REST semantics are known - .execute() is called</p> <p>Design constraints: - Must remain thin and imperative - Must not perform parsing or interpretation - Must not expose Gmail-specific types beyond this class</p> <p>Initialize the Gmail adapter.</p> <p>Parameters:</p> Name Type Description Default <code>auth_provider</code> <code>MailIntakeAuthProvider</code> <p>Authentication provider capable of supplying valid Gmail API credentials.</p> required <code>user_id</code> <code>str</code> <p>Gmail user identifier. Defaults to <code>\"me\"</code>.</p> <code>'me'</code>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.service","title":"service  <code>property</code>","text":"<pre><code>service: Any\n</code></pre> <p>Lazily initialize and return the Gmail API service client.</p> <p>Returns:</p> Type Description <code>Any</code> <p>Initialized Gmail API service instance.</p> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail service cannot be initialized.</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"<pre><code>fetch_message(message_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full Gmail message by message ID.</p> <p>Parameters:</p> Name Type Description Default <code>message_id</code> <code>str</code> <p>Gmail message identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native Gmail message payload.</p> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail API returns an error.</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"<pre><code>fetch_thread(thread_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full Gmail thread by thread ID.</p> <p>Parameters:</p> Name Type Description Default <code>thread_id</code> <code>str</code> <p>Gmail thread identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native Gmail thread payload.</p> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail API returns an error.</p>"},{"location":"mail_intake/adapters/#mail_intake.adapters.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"<pre><code>iter_message_refs(query: str) -&gt; Iterator[Dict[str, str]]\n</code></pre> <p>Iterate over message references matching the query.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Gmail search query string.</p> required <p>Yields:</p> Type Description <code>Dict[str, str]</code> <p>Dictionaries containing:</p> <code>Dict[str, str]</code> <ul> <li><code>message_id</code>: Gmail message ID</li> </ul> <code>Dict[str, str]</code> <ul> <li><code>thread_id</code>: Gmail thread ID</li> </ul> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail API returns an error.</p>"},{"location":"mail_intake/adapters/base/","title":"Base","text":""},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base","title":"mail_intake.adapters.base","text":"<p>Mail provider adapter contracts for Mail Intake.</p> <p>This module defines the provider-agnostic adapter interface used for read-only mail ingestion.</p> <p>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.</p>"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter","title":"MailIntakeAdapter","text":"<p>               Bases: <code>ABC</code></p> <p>Base adapter interface for mail providers.</p> <p>This interface defines the minimal contract required to: - Discover messages matching a query - Retrieve full message payloads - Retrieve full thread payloads</p> <p>Adapters are intentionally read-only and must not mutate provider state.</p>"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_message","title":"fetch_message  <code>abstractmethod</code>","text":"<pre><code>fetch_message(message_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full raw message by message identifier.</p> <p>Parameters:</p> Name Type Description Default <code>message_id</code> <code>str</code> <p>Provider-specific message identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native message payload</p> <code>Dict[str, Any]</code> <p>(e.g., Gmail message JSON structure).</p>"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.fetch_thread","title":"fetch_thread  <code>abstractmethod</code>","text":"<pre><code>fetch_thread(thread_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full raw thread by thread identifier.</p> <p>Parameters:</p> Name Type Description Default <code>thread_id</code> <code>str</code> <p>Provider-specific thread identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native thread payload.</p>"},{"location":"mail_intake/adapters/base/#mail_intake.adapters.base.MailIntakeAdapter.iter_message_refs","title":"iter_message_refs  <code>abstractmethod</code>","text":"<pre><code>iter_message_refs(query: str) -&gt; Iterator[Dict[str, str]]\n</code></pre> <p>Iterate over lightweight message references matching a query.</p> <p>Implementations must yield dictionaries containing at least: - <code>message_id</code>: Provider-specific message identifier - <code>thread_id</code>: Provider-specific thread identifier</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Provider-specific query string used to filter messages.</p> required <p>Yields:</p> Type Description <code>Dict[str, str]</code> <p>Dictionaries containing message and thread identifiers.</p> Example yield <p>{     \"message_id\": \"...\",     \"thread_id\": \"...\" }</p>"},{"location":"mail_intake/adapters/gmail/","title":"Gmail","text":""},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail","title":"mail_intake.adapters.gmail","text":"<p>Gmail adapter implementation for Mail Intake.</p> <p>This module provides a Gmail-specific implementation of the <code>MailIntakeAdapter</code> contract.</p> <p>It is the only place in the codebase where: - <code>googleapiclient</code> is imported - Gmail REST API semantics are known - Low-level <code>.execute()</code> calls are made</p> <p>All Gmail-specific behavior must be strictly contained within this module.</p>"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter","title":"MailIntakeGmailAdapter","text":"<pre><code>MailIntakeGmailAdapter(auth_provider: MailIntakeAuthProvider, user_id: str = 'me')\n</code></pre> <p>               Bases: <code>MailIntakeAdapter</code></p> <p>Gmail read-only adapter.</p> <p>This adapter implements the <code>MailIntakeAdapter</code> interface using the Gmail REST API. It translates the generic mail intake contract into Gmail-specific API calls.</p> <p>This class is the ONLY place where: - googleapiclient is imported - Gmail REST semantics are known - .execute() is called</p> <p>Design constraints: - Must remain thin and imperative - Must not perform parsing or interpretation - Must not expose Gmail-specific types beyond this class</p> <p>Initialize the Gmail adapter.</p> <p>Parameters:</p> Name Type Description Default <code>auth_provider</code> <code>MailIntakeAuthProvider</code> <p>Authentication provider capable of supplying valid Gmail API credentials.</p> required <code>user_id</code> <code>str</code> <p>Gmail user identifier. Defaults to <code>\"me\"</code>.</p> <code>'me'</code>"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.service","title":"service  <code>property</code>","text":"<pre><code>service: Any\n</code></pre> <p>Lazily initialize and return the Gmail API service client.</p> <p>Returns:</p> Type Description <code>Any</code> <p>Initialized Gmail API service instance.</p> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail service cannot be initialized.</p>"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_message","title":"fetch_message","text":"<pre><code>fetch_message(message_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full Gmail message by message ID.</p> <p>Parameters:</p> Name Type Description Default <code>message_id</code> <code>str</code> <p>Gmail message identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native Gmail message payload.</p> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail API returns an error.</p>"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.fetch_thread","title":"fetch_thread","text":"<pre><code>fetch_thread(thread_id: str) -&gt; Dict[str, Any]\n</code></pre> <p>Fetch a full Gmail thread by thread ID.</p> <p>Parameters:</p> Name Type Description Default <code>thread_id</code> <code>str</code> <p>Gmail thread identifier.</p> required <p>Returns:</p> Type Description <code>Dict[str, Any]</code> <p>Provider-native Gmail thread payload.</p> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail API returns an error.</p>"},{"location":"mail_intake/adapters/gmail/#mail_intake.adapters.gmail.MailIntakeGmailAdapter.iter_message_refs","title":"iter_message_refs","text":"<pre><code>iter_message_refs(query: str) -&gt; Iterator[Dict[str, str]]\n</code></pre> <p>Iterate over message references matching the query.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Gmail search query string.</p> required <p>Yields:</p> Type Description <code>Dict[str, str]</code> <p>Dictionaries containing:</p> <code>Dict[str, str]</code> <ul> <li><code>message_id</code>: Gmail message ID</li> </ul> <code>Dict[str, str]</code> <ul> <li><code>thread_id</code>: Gmail thread ID</li> </ul> <p>Raises:</p> Type Description <code>MailIntakeAdapterError</code> <p>If the Gmail API returns an error.</p>"},{"location":"mail_intake/auth/","title":"Auth","text":""},{"location":"mail_intake/auth/#mail_intake.auth","title":"mail_intake.auth","text":"<p>Authentication provider implementations for Mail Intake.</p> <p>This package defines the authentication layer used by mail adapters to obtain provider-specific credentials.</p> <p>It exposes: - A stable, provider-agnostic authentication contract - Concrete authentication providers for supported platforms</p> <p>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</p> <p>Consumers should depend on the abstract interface and use concrete implementations only where explicitly required.</p>"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"<p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class for authentication providers.</p> <p>This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.</p> <p>Authentication providers encapsulate all logic required to: - Acquire credentials from an external provider - Refresh or revalidate credentials as needed - Handle authentication-specific failure modes - Coordinate with credential persistence layers where applicable</p> <p>Mail adapters must treat returned credentials as opaque and provider-specific, relying only on the declared credential type expected by the adapter.</p>"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeAuthProvider.get_credentials","title":"get_credentials  <code>abstractmethod</code>","text":"<pre><code>get_credentials() -&gt; T\n</code></pre> <p>Retrieve valid, provider-specific credentials.</p> <p>This method is synchronous by design and represents the sole entry point through which adapters obtain authentication material.</p> <p>Implementations must either return credentials of the declared type <code>T</code> that are valid at the time of return or raise an authentication-specific exception.</p> <p>Returns:</p> Type Description <code>T</code> <p>Credentials of type <code>T</code> suitable for immediate use by the</p> <code>T</code> <p>corresponding mail adapter.</p> <p>Raises:</p> Type Description <code>Exception</code> <p>An authentication-specific exception indicating that credentials could not be obtained or validated.</p>"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"<pre><code>MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])\n</code></pre> <p>               Bases: <code>MailIntakeAuthProvider</code></p> <p>Google OAuth provider for Gmail access.</p> <p>This provider implements the <code>MailIntakeAuthProvider</code> interface using Google's OAuth 2.0 flow and credential management libraries.</p> <p>Responsibilities: - Load cached credentials from a credential store when available - Refresh expired credentials when possible - Initiate an interactive OAuth flow only when required - Persist refreshed or newly obtained credentials via the store</p> <p>This class is synchronous by design and maintains a minimal internal state.</p> <p>Initialize the Google authentication provider.</p> <p>Parameters:</p> Name Type Description Default <code>credentials_path</code> <code>str</code> <p>Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.</p> required <code>store</code> <code>CredentialStore[Any]</code> <p>Credential store responsible for persisting and retrieving Google OAuth credentials.</p> required <code>scopes</code> <code>Sequence[str]</code> <p>OAuth scopes required for Gmail access.</p> required"},{"location":"mail_intake/auth/#mail_intake.auth.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"<pre><code>get_credentials() -&gt; Any\n</code></pre> <p>Retrieve valid Google OAuth credentials.</p> <p>This method attempts to: 1. Load cached credentials from the configured credential store 2. Refresh expired credentials when possible 3. Perform an interactive OAuth login as a fallback 4. Persist valid credentials for future use</p> <p>Returns:</p> Type Description <code>Any</code> <p>A <code>google.oauth2.credentials.Credentials</code> instance suitable</p> <code>Any</code> <p>for use with Google API clients.</p> <p>Raises:</p> Type Description <code>MailIntakeAuthError</code> <p>If credentials cannot be loaded, refreshed, or obtained via interactive authentication.</p>"},{"location":"mail_intake/auth/base/","title":"Base","text":""},{"location":"mail_intake/auth/base/#mail_intake.auth.base","title":"mail_intake.auth.base","text":"<p>Authentication provider contracts for Mail Intake.</p> <p>This module defines the authentication abstraction layer used by mail adapters to obtain provider-specific credentials.</p> <p>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.</p>"},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider","title":"MailIntakeAuthProvider","text":"<p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class for authentication providers.</p> <p>This interface enforces a strict contract between authentication providers and mail adapters by requiring providers to explicitly declare the type of credentials they return.</p> <p>Authentication providers encapsulate all logic required to: - Acquire credentials from an external provider - Refresh or revalidate credentials as needed - Handle authentication-specific failure modes - Coordinate with credential persistence layers where applicable</p> <p>Mail adapters must treat returned credentials as opaque and provider-specific, relying only on the declared credential type expected by the adapter.</p>"},{"location":"mail_intake/auth/base/#mail_intake.auth.base.MailIntakeAuthProvider.get_credentials","title":"get_credentials  <code>abstractmethod</code>","text":"<pre><code>get_credentials() -&gt; T\n</code></pre> <p>Retrieve valid, provider-specific credentials.</p> <p>This method is synchronous by design and represents the sole entry point through which adapters obtain authentication material.</p> <p>Implementations must either return credentials of the declared type <code>T</code> that are valid at the time of return or raise an authentication-specific exception.</p> <p>Returns:</p> Type Description <code>T</code> <p>Credentials of type <code>T</code> suitable for immediate use by the</p> <code>T</code> <p>corresponding mail adapter.</p> <p>Raises:</p> Type Description <code>Exception</code> <p>An authentication-specific exception indicating that credentials could not be obtained or validated.</p>"},{"location":"mail_intake/auth/google/","title":"Google","text":""},{"location":"mail_intake/auth/google/#mail_intake.auth.google","title":"mail_intake.auth.google","text":"<p>Google authentication provider implementation for Mail Intake.</p> <p>This module provides a Google OAuth\u2013based authentication provider used primarily for Gmail access.</p> <p>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</p> <p>No Google authentication details should leak outside this module.</p>"},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth","title":"MailIntakeGoogleAuth","text":"<pre><code>MailIntakeGoogleAuth(credentials_path: str, store: CredentialStore[Any], scopes: Sequence[str])\n</code></pre> <p>               Bases: <code>MailIntakeAuthProvider</code></p> <p>Google OAuth provider for Gmail access.</p> <p>This provider implements the <code>MailIntakeAuthProvider</code> interface using Google's OAuth 2.0 flow and credential management libraries.</p> <p>Responsibilities: - Load cached credentials from a credential store when available - Refresh expired credentials when possible - Initiate an interactive OAuth flow only when required - Persist refreshed or newly obtained credentials via the store</p> <p>This class is synchronous by design and maintains a minimal internal state.</p> <p>Initialize the Google authentication provider.</p> <p>Parameters:</p> Name Type Description Default <code>credentials_path</code> <code>str</code> <p>Path to the Google OAuth client secrets file used to initiate the OAuth 2.0 flow.</p> required <code>store</code> <code>CredentialStore[Any]</code> <p>Credential store responsible for persisting and retrieving Google OAuth credentials.</p> required <code>scopes</code> <code>Sequence[str]</code> <p>OAuth scopes required for Gmail access.</p> required"},{"location":"mail_intake/auth/google/#mail_intake.auth.google.MailIntakeGoogleAuth.get_credentials","title":"get_credentials","text":"<pre><code>get_credentials() -&gt; Any\n</code></pre> <p>Retrieve valid Google OAuth credentials.</p> <p>This method attempts to: 1. Load cached credentials from the configured credential store 2. Refresh expired credentials when possible 3. Perform an interactive OAuth login as a fallback 4. Persist valid credentials for future use</p> <p>Returns:</p> Type Description <code>Any</code> <p>A <code>google.oauth2.credentials.Credentials</code> instance suitable</p> <code>Any</code> <p>for use with Google API clients.</p> <p>Raises:</p> Type Description <code>MailIntakeAuthError</code> <p>If credentials cannot be loaded, refreshed, or obtained via interactive authentication.</p>"},{"location":"mail_intake/credentials/","title":"Credentials","text":""},{"location":"mail_intake/credentials/#mail_intake.credentials","title":"mail_intake.credentials","text":"<p>Credential persistence interfaces and implementations for Mail Intake.</p> <p>This package defines the abstractions and concrete implementations used to persist authentication credentials across Mail Intake components.</p> <p>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.</p> <p>The package provides: - A generic <code>CredentialStore</code> abstraction defining the persistence contract - Local filesystem\u2013based storage for development and single-node use - Distributed, Redis-backed storage for production and scaled deployments</p> <p>Credential lifecycle management, interpretation, and security policy decisions remain the responsibility of authentication providers.</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore","title":"CredentialStore","text":"<p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining a generic persistence interface for authentication credentials.</p> <p>This interface separates credential lifecycle management from credential storage mechanics. Implementations are responsible only for persistence concerns, while authentication providers retain full control over credential creation, validation, refresh, and revocation logic.</p> <p>The store is intentionally agnostic to: - The concrete credential type being stored - The serialization format used to persist credentials - The underlying storage backend or durability guarantees</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.clear","title":"clear  <code>abstractmethod</code>","text":"<pre><code>clear() -&gt; None\n</code></pre> <p>Remove any persisted credentials from the store.</p> <p>This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable, and must ensure that no stale authentication material remains accessible.</p> <p>Implementations should treat this operation as idempotent.</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.load","title":"load  <code>abstractmethod</code>","text":"<pre><code>load() -&gt; Optional[T]\n</code></pre> <p>Load previously persisted credentials.</p> <p>Implementations should return <code>None</code> when no credentials are present or when stored credentials cannot be successfully decoded or deserialized.</p> <p>The store must not attempt to validate, refresh, or otherwise interpret the returned credentials.</p> <p>Returns:</p> Type Description <code>Optional[T]</code> <p>An instance of type <code>T</code> if credentials are available and</p> <code>Optional[T]</code> <p>loadable; otherwise <code>None</code>.</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.CredentialStore.save","title":"save  <code>abstractmethod</code>","text":"<pre><code>save(credentials: T) -&gt; None\n</code></pre> <p>Persist credentials to the underlying storage backend.</p> <p>This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence.</p> <p>Implementations are responsible for: - Ensuring durability appropriate to the deployment context - Applying encryption or access controls where required - Overwriting any previously stored credentials</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <code>T</code> <p>The credential object to persist.</p> required"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore","title":"PickleCredentialStore","text":"<pre><code>PickleCredentialStore(path: str)\n</code></pre> <p>               Bases: <code>CredentialStore[T]</code></p> <p>Filesystem-backed credential store using pickle serialization.</p> <p>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.</p> <p>This implementation: - Stores credentials on the local filesystem - Uses pickle for serialization and deserialization - Does not provide encryption, locking, or concurrency guarantees</p> <p>Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class.</p> <p>Initialize a pickle-backed credential store.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Filesystem path where credentials will be stored. The file will be created or overwritten as needed.</p> required"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.clear","title":"clear","text":"<pre><code>clear() -&gt; None\n</code></pre> <p>Remove persisted credentials from the local filesystem.</p> <p>This method deletes the credential file if it exists and should be treated as an idempotent operation.</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.load","title":"load","text":"<pre><code>load() -&gt; Optional[T]\n</code></pre> <p>Load credentials from the local filesystem.</p> <p>If the credential file does not exist or cannot be successfully deserialized, this method returns <code>None</code>.</p> <p>The store does not attempt to validate or interpret the returned credentials.</p> <p>Returns:</p> Type Description <code>Optional[T]</code> <p>An instance of type <code>T</code> if credentials are present and</p> <code>Optional[T]</code> <p>successfully deserialized; otherwise <code>None</code>.</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.PickleCredentialStore.save","title":"save","text":"<pre><code>save(credentials: T) -&gt; None\n</code></pre> <p>Persist credentials to the local filesystem.</p> <p>Any previously stored credentials at the configured path are overwritten.</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <code>T</code> <p>The credential object to persist.</p> required"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore","title":"RedisCredentialStore","text":"<pre><code>RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = None)\n</code></pre> <p>               Bases: <code>CredentialStore[T]</code></p> <p>Redis-backed implementation of <code>CredentialStore</code>.</p> <p>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.</p> <p>The store is intentionally generic and delegates all serialization concerns to caller-provided functions. This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited.</p> <p>This class is responsible only for persistence and retrieval. It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored.</p> <p>Initialize a Redis-backed credential store.</p> <p>Parameters:</p> Name Type Description Default <code>redis_client</code> <code>Any</code> <p>An initialized Redis client instance (for example, <code>redis.Redis</code> or a compatible interface) used to communicate with the Redis server.</p> required <code>key</code> <code>str</code> <p>The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.</p> required <code>serialize</code> <code>Callable[[T], bytes]</code> <p>A callable that converts a credential object of type <code>T</code> into a <code>bytes</code> representation suitable for storage in Redis.</p> required <code>deserialize</code> <code>Callable[[bytes], T]</code> <p>A callable that converts a <code>bytes</code> payload retrieved from Redis back into a credential object of type <code>T</code>.</p> required <code>ttl_seconds</code> <code>Optional[int]</code> <p>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 <code>None</code>, credentials are stored without an expiration.</p> <code>None</code>"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.clear","title":"clear","text":"<pre><code>clear() -&gt; None\n</code></pre> <p>Remove stored credentials from Redis.</p> <p>This operation deletes the configured Redis key if it exists. Implementations should treat this method as idempotent.</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.load","title":"load","text":"<pre><code>load() -&gt; Optional[T]\n</code></pre> <p>Load credentials from Redis.</p> <p>If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns <code>None</code>.</p> <p>The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable.</p> <p>Returns:</p> Type Description <code>Optional[T]</code> <p>An instance of type <code>T</code> if credentials are present and</p> <code>Optional[T]</code> <p>successfully deserialized; otherwise <code>None</code>.</p>"},{"location":"mail_intake/credentials/#mail_intake.credentials.RedisCredentialStore.save","title":"save","text":"<pre><code>save(credentials: T) -&gt; None\n</code></pre> <p>Persist credentials to Redis.</p> <p>Any previously stored credentials under the same key are overwritten. If a TTL is configured, the credentials will expire automatically after the specified duration.</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <code>T</code> <p>The credential object to persist.</p> required"},{"location":"mail_intake/credentials/pickle/","title":"Pickle","text":""},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle","title":"mail_intake.credentials.pickle","text":"<p>Local filesystem\u2013based credential persistence for Mail Intake.</p> <p>This module provides a file-backed implementation of the <code>CredentialStore</code> abstraction using Python's <code>pickle</code> module.</p> <p>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.</p> <p>Due to the security and portability risks associated with pickle-based serialization, this implementation is not suitable for distributed or untrusted environments.</p>"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore","title":"PickleCredentialStore","text":"<pre><code>PickleCredentialStore(path: str)\n</code></pre> <p>               Bases: <code>CredentialStore[T]</code></p> <p>Filesystem-backed credential store using pickle serialization.</p> <p>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.</p> <p>This implementation: - Stores credentials on the local filesystem - Uses pickle for serialization and deserialization - Does not provide encryption, locking, or concurrency guarantees</p> <p>Credential lifecycle management, validation, and refresh logic are explicitly out of scope for this class.</p> <p>Initialize a pickle-backed credential store.</p> <p>Parameters:</p> Name Type Description Default <code>path</code> <code>str</code> <p>Filesystem path where credentials will be stored. The file will be created or overwritten as needed.</p> required"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.clear","title":"clear","text":"<pre><code>clear() -&gt; None\n</code></pre> <p>Remove persisted credentials from the local filesystem.</p> <p>This method deletes the credential file if it exists and should be treated as an idempotent operation.</p>"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.load","title":"load","text":"<pre><code>load() -&gt; Optional[T]\n</code></pre> <p>Load credentials from the local filesystem.</p> <p>If the credential file does not exist or cannot be successfully deserialized, this method returns <code>None</code>.</p> <p>The store does not attempt to validate or interpret the returned credentials.</p> <p>Returns:</p> Type Description <code>Optional[T]</code> <p>An instance of type <code>T</code> if credentials are present and</p> <code>Optional[T]</code> <p>successfully deserialized; otherwise <code>None</code>.</p>"},{"location":"mail_intake/credentials/pickle/#mail_intake.credentials.pickle.PickleCredentialStore.save","title":"save","text":"<pre><code>save(credentials: T) -&gt; None\n</code></pre> <p>Persist credentials to the local filesystem.</p> <p>Any previously stored credentials at the configured path are overwritten.</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <code>T</code> <p>The credential object to persist.</p> required"},{"location":"mail_intake/credentials/redis/","title":"Redis","text":""},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis","title":"mail_intake.credentials.redis","text":"<p>Redis-backed credential persistence for Mail Intake.</p> <p>This module provides a Redis-based implementation of the <code>CredentialStore</code> abstraction, enabling credential persistence across distributed and horizontally scaled deployments.</p> <p>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.</p> <p>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</p> <p>This module is responsible solely for persistence concerns. Credential validation, refresh, rotation, and acquisition remain the responsibility of authentication provider implementations.</p>"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore","title":"RedisCredentialStore","text":"<pre><code>RedisCredentialStore(redis_client: Any, key: str, serialize: Callable[[T], bytes], deserialize: Callable[[bytes], T], ttl_seconds: Optional[int] = None)\n</code></pre> <p>               Bases: <code>CredentialStore[T]</code></p> <p>Redis-backed implementation of <code>CredentialStore</code>.</p> <p>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.</p> <p>The store is intentionally generic and delegates all serialization concerns to caller-provided functions. This avoids unsafe mechanisms such as pickle and allows credential formats to be explicitly controlled and audited.</p> <p>This class is responsible only for persistence and retrieval. It does not interpret, validate, refresh, or otherwise manage the lifecycle of the credentials being stored.</p> <p>Initialize a Redis-backed credential store.</p> <p>Parameters:</p> Name Type Description Default <code>redis_client</code> <code>Any</code> <p>An initialized Redis client instance (for example, <code>redis.Redis</code> or a compatible interface) used to communicate with the Redis server.</p> required <code>key</code> <code>str</code> <p>The Redis key under which credentials are stored. Callers are responsible for applying appropriate namespacing to avoid collisions.</p> required <code>serialize</code> <code>Callable[[T], bytes]</code> <p>A callable that converts a credential object of type <code>T</code> into a <code>bytes</code> representation suitable for storage in Redis.</p> required <code>deserialize</code> <code>Callable[[bytes], T]</code> <p>A callable that converts a <code>bytes</code> payload retrieved from Redis back into a credential object of type <code>T</code>.</p> required <code>ttl_seconds</code> <code>Optional[int]</code> <p>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 <code>None</code>, credentials are stored without an expiration.</p> <code>None</code>"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.clear","title":"clear","text":"<pre><code>clear() -&gt; None\n</code></pre> <p>Remove stored credentials from Redis.</p> <p>This operation deletes the configured Redis key if it exists. Implementations should treat this method as idempotent.</p>"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.load","title":"load","text":"<pre><code>load() -&gt; Optional[T]\n</code></pre> <p>Load credentials from Redis.</p> <p>If no value exists for the configured key, or if the stored payload cannot be successfully deserialized, this method returns <code>None</code>.</p> <p>The store does not attempt to validate the returned credentials or determine whether they are expired or otherwise usable.</p> <p>Returns:</p> Type Description <code>Optional[T]</code> <p>An instance of type <code>T</code> if credentials are present and</p> <code>Optional[T]</code> <p>successfully deserialized; otherwise <code>None</code>.</p>"},{"location":"mail_intake/credentials/redis/#mail_intake.credentials.redis.RedisCredentialStore.save","title":"save","text":"<pre><code>save(credentials: T) -&gt; None\n</code></pre> <p>Persist credentials to Redis.</p> <p>Any previously stored credentials under the same key are overwritten. If a TTL is configured, the credentials will expire automatically after the specified duration.</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <code>T</code> <p>The credential object to persist.</p> required"},{"location":"mail_intake/credentials/store/","title":"Store","text":""},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store","title":"mail_intake.credentials.store","text":"<p>Credential persistence abstractions for Mail Intake.</p> <p>This module defines the generic persistence contract used to store and retrieve authentication credentials across Mail Intake components.</p> <p>The <code>CredentialStore</code> 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.</p> <p>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.</p>"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore","title":"CredentialStore","text":"<p>               Bases: <code>ABC</code>, <code>Generic[T]</code></p> <p>Abstract base class defining a generic persistence interface for authentication credentials.</p> <p>This interface separates credential lifecycle management from credential storage mechanics. Implementations are responsible only for persistence concerns, while authentication providers retain full control over credential creation, validation, refresh, and revocation logic.</p> <p>The store is intentionally agnostic to: - The concrete credential type being stored - The serialization format used to persist credentials - The underlying storage backend or durability guarantees</p>"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.clear","title":"clear  <code>abstractmethod</code>","text":"<pre><code>clear() -&gt; None\n</code></pre> <p>Remove any persisted credentials from the store.</p> <p>This method is called when credentials are known to be invalid, revoked, corrupted, or otherwise unusable, and must ensure that no stale authentication material remains accessible.</p> <p>Implementations should treat this operation as idempotent.</p>"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.load","title":"load  <code>abstractmethod</code>","text":"<pre><code>load() -&gt; Optional[T]\n</code></pre> <p>Load previously persisted credentials.</p> <p>Implementations should return <code>None</code> when no credentials are present or when stored credentials cannot be successfully decoded or deserialized.</p> <p>The store must not attempt to validate, refresh, or otherwise interpret the returned credentials.</p> <p>Returns:</p> Type Description <code>Optional[T]</code> <p>An instance of type <code>T</code> if credentials are available and</p> <code>Optional[T]</code> <p>loadable; otherwise <code>None</code>.</p>"},{"location":"mail_intake/credentials/store/#mail_intake.credentials.store.CredentialStore.save","title":"save  <code>abstractmethod</code>","text":"<pre><code>save(credentials: T) -&gt; None\n</code></pre> <p>Persist credentials to the underlying storage backend.</p> <p>This method is invoked when credentials are newly obtained or have been refreshed and are known to be valid at the time of persistence.</p> <p>Implementations are responsible for: - Ensuring durability appropriate to the deployment context - Applying encryption or access controls where required - Overwriting any previously stored credentials</p> <p>Parameters:</p> Name Type Description Default <code>credentials</code> <code>T</code> <p>The credential object to persist.</p> required"},{"location":"mail_intake/ingestion/","title":"Ingestion","text":""},{"location":"mail_intake/ingestion/#mail_intake.ingestion","title":"mail_intake.ingestion","text":"<p>Mail ingestion orchestration for Mail Intake.</p> <p>This package contains high-level ingestion components responsible for coordinating mail retrieval, parsing, normalization, and model construction.</p> <p>It represents the top of the ingestion pipeline and is intended to be the primary interaction surface for library consumers.</p> <p>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</p> <p>Consumers are expected to construct a mail adapter and pass it to the ingestion layer to begin processing messages and threads.</p>"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader","title":"MailIntakeReader","text":"<pre><code>MailIntakeReader(adapter: MailIntakeAdapter)\n</code></pre> <p>High-level read-only ingestion interface.</p> <p>This class is the primary entry point for consumers of the Mail Intake library.</p> <p>It orchestrates the full ingestion pipeline: - Querying the adapter for message references - Fetching raw provider messages - Parsing and normalizing message data - Constructing domain models</p> <p>This class is intentionally: - Provider-agnostic - Stateless beyond iteration scope - Read-only</p> <p>Initialize the mail reader.</p> <p>Parameters:</p> Name Type Description Default <code>adapter</code> <code>MailIntakeAdapter</code> <p>Mail adapter implementation used to retrieve raw messages and threads from a mail provider.</p> required"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_messages","title":"iter_messages","text":"<pre><code>iter_messages(query: str) -&gt; Iterator[MailIntakeMessage]\n</code></pre> <p>Iterate over parsed messages matching a provider query.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Provider-specific query string used to filter messages.</p> required <p>Yields:</p> Type Description <code>MailIntakeMessage</code> <p>Fully parsed and normalized <code>MailIntakeMessage</code> instances.</p> <p>Raises:</p> Type Description <code>MailIntakeParsingError</code> <p>If a message cannot be parsed.</p>"},{"location":"mail_intake/ingestion/#mail_intake.ingestion.MailIntakeReader.iter_threads","title":"iter_threads","text":"<pre><code>iter_threads(query: str) -&gt; Iterator[MailIntakeThread]\n</code></pre> <p>Iterate over threads constructed from messages matching a query.</p> <p>Messages are grouped by <code>thread_id</code> and yielded as complete thread objects containing all associated messages.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Provider-specific query string used to filter messages.</p> required <p>Returns:</p> Type Description <code>Iterator[MailIntakeThread]</code> <p>An iterator of <code>MailIntakeThread</code> instances.</p> <p>Raises:</p> Type Description <code>MailIntakeParsingError</code> <p>If a message cannot be parsed.</p>"},{"location":"mail_intake/ingestion/reader/","title":"Reader","text":""},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader","title":"mail_intake.ingestion.reader","text":"<p>High-level mail ingestion orchestration for Mail Intake.</p> <p>This module provides the primary, provider-agnostic entry point for reading and processing mail data.</p> <p>It coordinates: - Mail adapter access - Message and thread iteration - Header and body parsing - Normalization and model construction</p> <p>No provider-specific logic or API semantics are permitted in this layer.</p>"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader","title":"MailIntakeReader","text":"<pre><code>MailIntakeReader(adapter: MailIntakeAdapter)\n</code></pre> <p>High-level read-only ingestion interface.</p> <p>This class is the primary entry point for consumers of the Mail Intake library.</p> <p>It orchestrates the full ingestion pipeline: - Querying the adapter for message references - Fetching raw provider messages - Parsing and normalizing message data - Constructing domain models</p> <p>This class is intentionally: - Provider-agnostic - Stateless beyond iteration scope - Read-only</p> <p>Initialize the mail reader.</p> <p>Parameters:</p> Name Type Description Default <code>adapter</code> <code>MailIntakeAdapter</code> <p>Mail adapter implementation used to retrieve raw messages and threads from a mail provider.</p> required"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_messages","title":"iter_messages","text":"<pre><code>iter_messages(query: str) -&gt; Iterator[MailIntakeMessage]\n</code></pre> <p>Iterate over parsed messages matching a provider query.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Provider-specific query string used to filter messages.</p> required <p>Yields:</p> Type Description <code>MailIntakeMessage</code> <p>Fully parsed and normalized <code>MailIntakeMessage</code> instances.</p> <p>Raises:</p> Type Description <code>MailIntakeParsingError</code> <p>If a message cannot be parsed.</p>"},{"location":"mail_intake/ingestion/reader/#mail_intake.ingestion.reader.MailIntakeReader.iter_threads","title":"iter_threads","text":"<pre><code>iter_threads(query: str) -&gt; Iterator[MailIntakeThread]\n</code></pre> <p>Iterate over threads constructed from messages matching a query.</p> <p>Messages are grouped by <code>thread_id</code> and yielded as complete thread objects containing all associated messages.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>str</code> <p>Provider-specific query string used to filter messages.</p> required <p>Returns:</p> Type Description <code>Iterator[MailIntakeThread]</code> <p>An iterator of <code>MailIntakeThread</code> instances.</p> <p>Raises:</p> Type Description <code>MailIntakeParsingError</code> <p>If a message cannot be parsed.</p>"},{"location":"mail_intake/models/","title":"Models","text":""},{"location":"mail_intake/models/#mail_intake.models","title":"mail_intake.models","text":"<p>Domain models for Mail Intake.</p> <p>This package defines the canonical, provider-agnostic data models used throughout the Mail Intake ingestion pipeline.</p> <p>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</p> <p>These models form the core internal data contract of the library.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage","title":"MailIntakeMessage  <code>dataclass</code>","text":"<pre><code>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</code></pre> <p>Canonical internal representation of a single email message.</p> <p>This model represents a fully parsed and normalized email message. It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing.</p> <p>No provider-specific identifiers, payloads, or API semantics should appear in this model.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.body_text","title":"body_text  <code>instance-attribute</code>","text":"<pre><code>body_text: str\n</code></pre> <p>Extracted plain-text body content of the message.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_email","title":"from_email  <code>instance-attribute</code>","text":"<pre><code>from_email: str\n</code></pre> <p>Sender email address.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.from_name","title":"from_name  <code>instance-attribute</code>","text":"<pre><code>from_name: Optional[str]\n</code></pre> <p>Optional human-readable sender name.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.message_id","title":"message_id  <code>instance-attribute</code>","text":"<pre><code>message_id: str\n</code></pre> <p>Provider-specific message identifier.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.raw_headers","title":"raw_headers  <code>instance-attribute</code>","text":"<pre><code>raw_headers: Dict[str, str]\n</code></pre> <p>Normalized mapping of message headers (header name \u2192 value).</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.snippet","title":"snippet  <code>instance-attribute</code>","text":"<pre><code>snippet: str\n</code></pre> <p>Short provider-supplied preview snippet of the message.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.subject","title":"subject  <code>instance-attribute</code>","text":"<pre><code>subject: str\n</code></pre> <p>Raw subject line of the message.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.thread_id","title":"thread_id  <code>instance-attribute</code>","text":"<pre><code>thread_id: str\n</code></pre> <p>Provider-specific thread identifier to which this message belongs.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeMessage.timestamp","title":"timestamp  <code>instance-attribute</code>","text":"<pre><code>timestamp: datetime\n</code></pre> <p>Message timestamp as a timezone-naive UTC datetime.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread","title":"MailIntakeThread  <code>dataclass</code>","text":"<pre><code>MailIntakeThread(thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...)\n</code></pre> <p>Canonical internal representation of an email thread.</p> <p>A thread groups multiple related messages under a single subject and participant set. It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions.</p> <p>This model is provider-agnostic and safe to persist.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.last_activity_at","title":"last_activity_at  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>last_activity_at: Optional[datetime] = None\n</code></pre> <p>Timestamp of the most recent message in the thread.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.messages","title":"messages  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>messages: List[MailIntakeMessage] = field(default_factory=list)\n</code></pre> <p>Ordered list of messages belonging to this thread.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.normalized_subject","title":"normalized_subject  <code>instance-attribute</code>","text":"<pre><code>normalized_subject: str\n</code></pre> <p>Normalized subject line used to group related messages.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.participants","title":"participants  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>participants: Set[str] = field(default_factory=set)\n</code></pre> <p>Set of unique participant email addresses observed in the thread.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.thread_id","title":"thread_id  <code>instance-attribute</code>","text":"<pre><code>thread_id: str\n</code></pre> <p>Provider-specific thread identifier.</p>"},{"location":"mail_intake/models/#mail_intake.models.MailIntakeThread.add_message","title":"add_message","text":"<pre><code>add_message(message: MailIntakeMessage) -&gt; None\n</code></pre> <p>Add a message to the thread and update derived fields.</p> <p>This method: - Appends the message to the thread - Tracks unique participants - Updates the last activity timestamp</p> <p>Parameters:</p> Name Type Description Default <code>message</code> <code>MailIntakeMessage</code> <p>Parsed mail message to add to the thread.</p> required"},{"location":"mail_intake/models/message/","title":"Message","text":""},{"location":"mail_intake/models/message/#mail_intake.models.message","title":"mail_intake.models.message","text":"<p>Message domain models for Mail Intake.</p> <p>This module defines the canonical, provider-agnostic representation of an individual email message as used internally by the Mail Intake ingestion pipeline.</p> <p>Models in this module are safe to persist and must not contain any provider-specific fields or semantics.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage","title":"MailIntakeMessage  <code>dataclass</code>","text":"<pre><code>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</code></pre> <p>Canonical internal representation of a single email message.</p> <p>This model represents a fully parsed and normalized email message. It is intentionally provider-agnostic and suitable for persistence, indexing, and downstream processing.</p> <p>No provider-specific identifiers, payloads, or API semantics should appear in this model.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.body_text","title":"body_text  <code>instance-attribute</code>","text":"<pre><code>body_text: str\n</code></pre> <p>Extracted plain-text body content of the message.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_email","title":"from_email  <code>instance-attribute</code>","text":"<pre><code>from_email: str\n</code></pre> <p>Sender email address.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.from_name","title":"from_name  <code>instance-attribute</code>","text":"<pre><code>from_name: Optional[str]\n</code></pre> <p>Optional human-readable sender name.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.message_id","title":"message_id  <code>instance-attribute</code>","text":"<pre><code>message_id: str\n</code></pre> <p>Provider-specific message identifier.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.raw_headers","title":"raw_headers  <code>instance-attribute</code>","text":"<pre><code>raw_headers: Dict[str, str]\n</code></pre> <p>Normalized mapping of message headers (header name \u2192 value).</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.snippet","title":"snippet  <code>instance-attribute</code>","text":"<pre><code>snippet: str\n</code></pre> <p>Short provider-supplied preview snippet of the message.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.subject","title":"subject  <code>instance-attribute</code>","text":"<pre><code>subject: str\n</code></pre> <p>Raw subject line of the message.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.thread_id","title":"thread_id  <code>instance-attribute</code>","text":"<pre><code>thread_id: str\n</code></pre> <p>Provider-specific thread identifier to which this message belongs.</p>"},{"location":"mail_intake/models/message/#mail_intake.models.message.MailIntakeMessage.timestamp","title":"timestamp  <code>instance-attribute</code>","text":"<pre><code>timestamp: datetime\n</code></pre> <p>Message timestamp as a timezone-naive UTC datetime.</p>"},{"location":"mail_intake/models/thread/","title":"Thread","text":""},{"location":"mail_intake/models/thread/#mail_intake.models.thread","title":"mail_intake.models.thread","text":"<p>Thread domain models for Mail Intake.</p> <p>This module defines the canonical, provider-agnostic representation of an email thread as used internally by the Mail Intake ingestion pipeline.</p> <p>Threads group related messages and serve as the primary unit of reasoning for higher-level correspondence workflows.</p>"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread","title":"MailIntakeThread  <code>dataclass</code>","text":"<pre><code>MailIntakeThread(thread_id: str, normalized_subject: str, participants: Set[str] = ..., messages: List[MailIntakeMessage] = ..., last_activity_at: Optional[datetime] = ...)\n</code></pre> <p>Canonical internal representation of an email thread.</p> <p>A thread groups multiple related messages under a single subject and participant set. It is designed to support reasoning over conversational context such as job applications, interviews, follow-ups, and ongoing discussions.</p> <p>This model is provider-agnostic and safe to persist.</p>"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.last_activity_at","title":"last_activity_at  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>last_activity_at: Optional[datetime] = None\n</code></pre> <p>Timestamp of the most recent message in the thread.</p>"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.messages","title":"messages  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>messages: List[MailIntakeMessage] = field(default_factory=list)\n</code></pre> <p>Ordered list of messages belonging to this thread.</p>"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.normalized_subject","title":"normalized_subject  <code>instance-attribute</code>","text":"<pre><code>normalized_subject: str\n</code></pre> <p>Normalized subject line used to group related messages.</p>"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.participants","title":"participants  <code>class-attribute</code> <code>instance-attribute</code>","text":"<pre><code>participants: Set[str] = field(default_factory=set)\n</code></pre> <p>Set of unique participant email addresses observed in the thread.</p>"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.thread_id","title":"thread_id  <code>instance-attribute</code>","text":"<pre><code>thread_id: str\n</code></pre> <p>Provider-specific thread identifier.</p>"},{"location":"mail_intake/models/thread/#mail_intake.models.thread.MailIntakeThread.add_message","title":"add_message","text":"<pre><code>add_message(message: MailIntakeMessage) -&gt; None\n</code></pre> <p>Add a message to the thread and update derived fields.</p> <p>This method: - Appends the message to the thread - Tracks unique participants - Updates the last activity timestamp</p> <p>Parameters:</p> Name Type Description Default <code>message</code> <code>MailIntakeMessage</code> <p>Parsed mail message to add to the thread.</p> required"},{"location":"mail_intake/parsers/","title":"Parsers","text":""},{"location":"mail_intake/parsers/#mail_intake.parsers","title":"mail_intake.parsers","text":"<p>Message parsing utilities for Mail Intake.</p> <p>This package contains provider-aware but adapter-agnostic parsing helpers used to extract and normalize structured information from raw mail payloads.</p> <p>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</p> <p>This package does not: - Perform network or IO operations - Contain provider API logic - Construct domain models directly</p> <p>Parsing functions are designed to be composable and are orchestrated by the ingestion layer.</p>"},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_body","title":"extract_body","text":"<pre><code>extract_body(payload: Dict[str, Any]) -&gt; str\n</code></pre> <p>Extract the best-effort message body from a Gmail payload.</p> <p>Priority: 1. text/plain 2. text/html (stripped to text) 3. Single-part body 4. empty string (if nothing usable found)</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Dict[str, Any]</code> <p>Provider-native message payload dictionary.</p> required <p>Returns:</p> Type Description <code>str</code> <p>Extracted plain-text message body.</p>"},{"location":"mail_intake/parsers/#mail_intake.parsers.extract_sender","title":"extract_sender","text":"<pre><code>extract_sender(headers: Dict[str, str]) -&gt; Tuple[str, Optional[str]]\n</code></pre> <p>Extract sender email and optional display name from headers.</p> <p>This function parses the <code>From</code> header and attempts to extract: - Sender email address - Optional human-readable display name</p> <p>Parameters:</p> Name Type Description Default <code>headers</code> <code>Dict[str, str]</code> <p>Normalized header dictionary as returned by :func:<code>parse_headers</code>.</p> required <p>Returns:</p> Type Description <code>str</code> <p>A tuple <code>(email, name)</code> where:</p> <code>Optional[str]</code> <ul> <li><code>email</code> is the sender email address</li> </ul> <code>Tuple[str, Optional[str]]</code> <ul> <li><code>name</code> is the display name, or <code>None</code> if unavailable</li> </ul> <p>Examples:</p> <p><code>\"John Doe &lt;john@example.com&gt;\"</code> \u2192 <code>(\"john@example.com\", \"John Doe\")</code> <code>\"john@example.com\"</code> \u2192 <code>(\"john@example.com\", None)</code></p>"},{"location":"mail_intake/parsers/#mail_intake.parsers.normalize_subject","title":"normalize_subject","text":"<pre><code>normalize_subject(subject: str) -&gt; str\n</code></pre> <p>Normalize an email subject for thread-level comparison.</p> <p>Operations: - Strips common prefixes such as <code>Re:</code>, <code>Fwd:</code>, and <code>FW:</code> - Repeats prefix stripping to handle stacked prefixes - Collapses excessive whitespace - Preserves original casing (no lowercasing)</p> <p>This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject</code> <code>str</code> <p>Raw subject line from a message header.</p> required <p>Returns:</p> Type Description <code>str</code> <p>Normalized subject string suitable for thread grouping.</p>"},{"location":"mail_intake/parsers/#mail_intake.parsers.parse_headers","title":"parse_headers","text":"<pre><code>parse_headers(raw_headers: List[Dict[str, str]]) -&gt; Dict[str, str]\n</code></pre> <p>Convert a list of Gmail-style headers into a normalized dict.</p> <p>Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings. This function normalizes them into a case-insensitive dictionary keyed by lowercase header names.</p> <p>Parameters:</p> Name Type Description Default <code>raw_headers</code> <code>List[Dict[str, str]]</code> <p>List of header dictionaries, each containing <code>name</code> and <code>value</code> keys.</p> required <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>Dictionary mapping lowercase header names to stripped values.</p> Example <p>Input:     [         {\"name\": \"From\", \"value\": \"John Doe john@example.com\"},         {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},     ]</p> <p>Output:     {         \"from\": \"John Doe john@example.com\",         \"subject\": \"Re: Interview Update\",     }</p>"},{"location":"mail_intake/parsers/body/","title":"Body","text":""},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body","title":"mail_intake.parsers.body","text":"<p>Message body extraction utilities for Mail Intake.</p> <p>This module contains helper functions for extracting a best-effort plain-text body from provider-native message payloads.</p> <p>The logic is intentionally tolerant of malformed or partial data and prefers human-readable text over fidelity to original formatting.</p>"},{"location":"mail_intake/parsers/body/#mail_intake.parsers.body.extract_body","title":"extract_body","text":"<pre><code>extract_body(payload: Dict[str, Any]) -&gt; str\n</code></pre> <p>Extract the best-effort message body from a Gmail payload.</p> <p>Priority: 1. text/plain 2. text/html (stripped to text) 3. Single-part body 4. empty string (if nothing usable found)</p> <p>Parameters:</p> Name Type Description Default <code>payload</code> <code>Dict[str, Any]</code> <p>Provider-native message payload dictionary.</p> required <p>Returns:</p> Type Description <code>str</code> <p>Extracted plain-text message body.</p>"},{"location":"mail_intake/parsers/headers/","title":"Headers","text":""},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers","title":"mail_intake.parsers.headers","text":"<p>Message header parsing utilities for Mail Intake.</p> <p>This module provides helper functions for normalizing and extracting useful information from provider-native message headers.</p> <p>The functions here are intentionally simple and tolerant of malformed or incomplete header data.</p>"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.extract_sender","title":"extract_sender","text":"<pre><code>extract_sender(headers: Dict[str, str]) -&gt; Tuple[str, Optional[str]]\n</code></pre> <p>Extract sender email and optional display name from headers.</p> <p>This function parses the <code>From</code> header and attempts to extract: - Sender email address - Optional human-readable display name</p> <p>Parameters:</p> Name Type Description Default <code>headers</code> <code>Dict[str, str]</code> <p>Normalized header dictionary as returned by :func:<code>parse_headers</code>.</p> required <p>Returns:</p> Type Description <code>str</code> <p>A tuple <code>(email, name)</code> where:</p> <code>Optional[str]</code> <ul> <li><code>email</code> is the sender email address</li> </ul> <code>Tuple[str, Optional[str]]</code> <ul> <li><code>name</code> is the display name, or <code>None</code> if unavailable</li> </ul> <p>Examples:</p> <p><code>\"John Doe &lt;john@example.com&gt;\"</code> \u2192 <code>(\"john@example.com\", \"John Doe\")</code> <code>\"john@example.com\"</code> \u2192 <code>(\"john@example.com\", None)</code></p>"},{"location":"mail_intake/parsers/headers/#mail_intake.parsers.headers.parse_headers","title":"parse_headers","text":"<pre><code>parse_headers(raw_headers: List[Dict[str, str]]) -&gt; Dict[str, str]\n</code></pre> <p>Convert a list of Gmail-style headers into a normalized dict.</p> <p>Provider payloads (such as Gmail) typically represent headers as a list of name/value mappings. This function normalizes them into a case-insensitive dictionary keyed by lowercase header names.</p> <p>Parameters:</p> Name Type Description Default <code>raw_headers</code> <code>List[Dict[str, str]]</code> <p>List of header dictionaries, each containing <code>name</code> and <code>value</code> keys.</p> required <p>Returns:</p> Type Description <code>Dict[str, str]</code> <p>Dictionary mapping lowercase header names to stripped values.</p> Example <p>Input:     [         {\"name\": \"From\", \"value\": \"John Doe john@example.com\"},         {\"name\": \"Subject\", \"value\": \"Re: Interview Update\"},     ]</p> <p>Output:     {         \"from\": \"John Doe john@example.com\",         \"subject\": \"Re: Interview Update\",     }</p>"},{"location":"mail_intake/parsers/subject/","title":"Subject","text":""},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject","title":"mail_intake.parsers.subject","text":"<p>Subject line normalization utilities for Mail Intake.</p> <p>This module provides helper functions for normalizing email subject lines to enable reliable thread-level comparison and grouping.</p> <p>Normalization is intentionally conservative to avoid altering semantic meaning while removing common reply and forward prefixes.</p>"},{"location":"mail_intake/parsers/subject/#mail_intake.parsers.subject.normalize_subject","title":"normalize_subject","text":"<pre><code>normalize_subject(subject: str) -&gt; str\n</code></pre> <p>Normalize an email subject for thread-level comparison.</p> <p>Operations: - Strips common prefixes such as <code>Re:</code>, <code>Fwd:</code>, and <code>FW:</code> - Repeats prefix stripping to handle stacked prefixes - Collapses excessive whitespace - Preserves original casing (no lowercasing)</p> <p>This function is intentionally conservative and avoids aggressive transformations that could alter the semantic meaning of the subject.</p> <p>Parameters:</p> Name Type Description Default <code>subject</code> <code>str</code> <p>Raw subject line from a message header.</p> required <p>Returns:</p> Type Description <code>str</code> <p>Normalized subject string suitable for thread grouping.</p>"}]}