# 🖥️ 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.