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
105 lines
2.8 KiB
Markdown
105 lines
2.8 KiB
Markdown
# 🖥️ How to Use
|
|
|
|
This page walks through authenticating, ingesting, and parsing mail with the
|
|
built-in Gmail support.
|
|
|
|
---
|
|
|
|
## 🔐 Authentication
|
|
|
|
Create a credential store and an auth provider:
|
|
|
|
```python
|
|
from mail_intake.auth import MailIntakeGoogleAuth
|
|
from mail_intake.credentials import PickleCredentialStore, RedisCredentialStore
|
|
|
|
store = PickleCredentialStore(path="token.pickle") # local dev
|
|
|
|
auth = MailIntakeGoogleAuth(
|
|
credentials_path="credentials.json", # your OAuth client file
|
|
store=store,
|
|
scopes=["https://www.googleapis.com/auth/gmail.readonly"],
|
|
)
|
|
```
|
|
|
|
> OAuth credentials come from the Google Cloud Console and are provided via
|
|
> file paths — never hard-code tokens or secrets in source. Once authorized,
|
|
> the token is persisted by the credential store and refreshed automatically.
|
|
|
|
For distributed deployments, use Redis instead of pickle:
|
|
|
|
```python
|
|
store = RedisCredentialStore(redis_client=redis_client) # production
|
|
```
|
|
|
|
---
|
|
|
|
## 📥 Ingesting messages
|
|
|
|
Build an adapter and a reader, then iterate:
|
|
|
|
```python
|
|
from mail_intake.ingestion import MailIntakeReader
|
|
from mail_intake.adapters import MailIntakeGmailAdapter
|
|
|
|
adapter = MailIntakeGmailAdapter(auth_provider=auth)
|
|
reader = MailIntakeReader(adapter)
|
|
|
|
for message in reader.iter_messages("from:recruiter@example.com"):
|
|
print(message.subject, message.from_email, message.timestamp)
|
|
```
|
|
|
|
Access the full model:
|
|
|
|
```python
|
|
message.message_id # provider id
|
|
message.thread_id
|
|
message.body_text # plain-text body
|
|
message.raw_headers # unmodified headers dict
|
|
```
|
|
|
|
---
|
|
|
|
## 🔖 Ingesting threads
|
|
|
|
```python
|
|
for thread in reader.iter_threads("subject:Interview"):
|
|
print(thread.normalized_subject)
|
|
print(thread.participants)
|
|
print(len(thread.messages))
|
|
print(thread.last_activity_at)
|
|
```
|
|
|
|
`MailIntakeThread` aggregates its messages, participants, and last activity.
|
|
|
|
---
|
|
|
|
## 🧪 Parsers
|
|
|
|
Parsers normalize provider payloads and are used by the reader internally.
|
|
They are also importable on their own:
|
|
|
|
```python
|
|
from mail_intake.parsers import extract_body, parse_headers, normalize_subject
|
|
```
|
|
|
|
- `extract_body(...)` — plain-text body extraction.
|
|
- `parse_headers(...)` — structured header parsing.
|
|
- `extract_sender(...)` — sender email/name extraction.
|
|
- `normalize_subject(...)` — subject normalization for threading.
|
|
|
|
---
|
|
|
|
## ✅ Checklist
|
|
|
|
1. Provide OAuth credentials via a file path and a credential store.
|
|
2. Build the `MailIntakeGoogleAuth` provider with the Gmail read-only scope.
|
|
3. Wrap the adapter in a `MailIntakeReader`.
|
|
4. Consume `iter_messages` / `iter_threads`; never call provider APIs directly.
|
|
|
|
---
|
|
|
|
## 📚 Read Next
|
|
|
|
- [Overview](01_overview.md) — layers and domain models.
|
|
- [Extending Mail Intake](03_extending.md) — custom providers and stores. |