Skip to content

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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:

1
store = RedisCredentialStore(redis_client=redis_client)     # production

📥 Ingesting messages

Build an adapter and a reader, then iterate:

1
2
3
4
5
6
7
8
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:

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

🔖 Ingesting threads

1
2
3
4
5
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:

1
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.