Vishesh 'ironeagle' Bangotra
370d1272bf
- Add hand-written wiki (index, overview, how-to, extending, dev) following the platform anatomy - Remove stale nested docs/lib/mail_intake and regenerate the flat lib reference to match docforge.nav.yml - Regenerate MCP bundle with standardized docstrings
71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# 📬 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 |