Skip to content

📬 Mail Intake — Provider-Agnostic Email Ingestion

Mail Intake is a contract-first, read-only email ingestion framework. It pulls mail from external providers (such as Gmail), parses and normalizes it into clean, provider-agnostic domain models — ready to persist, index, or analyze downstream.

Doc model: this wiki is written for humans — how‑to guides and extension recipes. The authoritative API contracts live in the code (GSDFC docstrings) and the machine‑readable bundle under docs/mcp/.

🚀 Key Features

  • 📬 Read-only ingestion — never mutates provider state
  • 🧩 Contract-first layers — adapters, parsers, and readers separated
  • ✉️ Provider-agnostic models — MailIntakeMessage / MailIntakeThread have no provider internals
  • 🔐 Extensible auth — pluggable auth providers and credential stores (pickle for dev, Redis for production)
  • 🧪 Deterministic & testable — no implicit global state or env reads
  • 📊 Gmail support — reference adapter built on the official Google APIs

⚡ Quick Start

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
from mail_intake.ingestion import MailIntakeReader
from mail_intake.adapters import MailIntakeGmailAdapter
from mail_intake.auth import MailIntakeGoogleAuth
from mail_intake.credentials import PickleCredentialStore

store = PickleCredentialStore(path="token.pickle")

auth = MailIntakeGoogleAuth(
    credentials_path="credentials.json",
    store=store,
    scopes=["https://www.googleapis.com/auth/gmail.readonly"],
)

adapter = MailIntakeGmailAdapter(auth_provider=auth)
reader = MailIntakeReader(adapter)

for message in reader.iter_messages("from:recruiter@example.com"):
    print(message.subject, message.from_email)

📁 Documentation Structure

Section What you'll find
Overview Layers, domain models, and design guarantees
How to Use Gmail ingestion, parsing, and credential stores
Extending Mail Intake Custom adapters, auth providers, stores
Development Setup, tests, and regenerating docs

© Aetoskia Internal — mail-intake 0.0.2