Inbox Manager

Authorize, read, triage, archive, trash, and summarize Gmail inboxes across multiple accounts. Uses Gmail API with OAuth.

Manage multiple Gmail accounts through a single Google Cloud project. One OAuth client, separate token per account.

Architecture

secrets/inbox/
  client_secret.json            — OAuth 2.0 Desktop client credentials (shared)
  accounts.json                  — {"[e-mail]": {"label": ..., "token_file": "token-..."}}
  token-account-at-gmail-dot-com.json  — per-account OAuth token

scripts/inbox/
  inbox-auth-final.py           — one-shot OAuth: opens browser, saves token
  inbox-check.py                — read/filter/triage/delete via Gmail API

Adding a new account

1. Run python3 scripts/inbox-auth-final.py <email> on machine with browser access
2. Log in to Gmail in the Chromium popup, authorize
3. Token auto-saves to secrets/inbox/token-<sanitized>.json
4. accounts.json auto-updated

Sanitization: @ → -at-, . → -dot-

Gmail API scopes used

• gmail.readonly — read messages
• gmail.modify — trash, archive, mark read, label

Not used: gmail.send / gmail.compose (no auto-sending unless explicitly added)

Operations

List inbox

GET /gmail/v1/users/me/messages?labelIds=INBOX&maxResults=N
GET /gmail/v1/users/me/messages/{id}?format=metadata&metadataHeaders=From,Subject,Date

Search/filter

Use Gmail query syntax via q parameter:

• from:traveloka — all from sender
• is:unread — unread only
• -from:accounts.google.com — exclude security alerts
• after:2026/05/01 — date filter

Delete/trash

POST /gmail/v1/users/me/messages/{id}/trash

Batch via new_batch_http_request() for bulk operations (100 per batch).

Cleanup rules (spamforhobo examples)

Sender	Action	Reason
Traveloka	Trash	Promo emails
Flokk	Trash	Promo emails
FossilEra	Trash	Promo emails
TIDAL monthly reports	Trash	Old newsletters
BloomThis	Trash	Feedback/promo
Helpling	Keep	Actual reminders
Splitwise	Keep	Balance updates
SRX	Keep	Property updates
NLB	Keep	Account notifications

Security notes

• Tokens contain refresh tokens — treat as sensitive (NEVER commit)
• Google may flag new accounts accessed via CLI-only; use established accounts
• OAuth tokens auto-refresh; no manual reauth needed unless revoked
• 3 security alerts on first auth are normal (Google notifying account owner)