mail-intake/docs/wiki/index.md

📬 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

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

---

🔗 Related Resources

• Source Code: Gitea Repository
• Internal PyPI: pip.aetoskia.com/simple/mail-intake
• CI: Builds and publishes tagged releases, gated on black / ruff / mypy / pytest.

---

© Aetoskia Internal — mail-intake 0.0.2