mail-intake/docs/wiki/02_how_to_use.md

🖥️ 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:

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:

store = RedisCredentialStore(redis_client=redis_client)     # production

---

📥 Ingesting messages

Build an adapter and a reader, then iterate:

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:

message.message_id    # provider id
message.thread_id
message.body_text     # plain-text body
message.raw_headers   # unmodified headers dict

---

🔖 Ingesting threads

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:

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 — layers and domain models.
• Extending Mail Intake — custom providers and stores.