# 📬 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

```python
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](01_overview.md) | Layers, domain models, and design guarantees |
| [How to Use](02_how_to_use.md) | Gmail ingestion, parsing, and credential stores |
| [Extending Mail Intake](03_extending.md) | Custom adapters, auth providers, stores |
| [Development](04_development.md) | Setup, tests, and regenerating docs |

---

## 🔗 Related Resources

* **Source Code:** [Gitea Repository](https://git.aetoskia.com/aetos/mail-intake)
* **Internal PyPI:** [pip.aetoskia.com/simple/mail-intake](https://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