Skip to main content

Gmail

Gmail is a least-privilege, read-only mailbox connector — separate from the Email BCC / Attachment Inbox connector, which is the one actually in production today.

Status​

🟡 Built, needs Workspace approval. The code is complete; what's missing is governance, not engineering.

Function​

gmail-sync

Scope and access model​

Gmail access is restricted to gmail.readonly and requires domain-wide delegation to one explicit mailbox — GOOGLE_GMAIL_SUBJECT, not a whole-domain mirror. Connector credentials are resolved only from Edge secret names (GOOGLE_WORKSPACE_SA_JSON, falling back to GDRIVE_SA_JSON/GOOGLE_DRIVE_JSON) — the same service-account pattern Calendar and Drive use, authenticated as an RS256 JWT-bearer token exchanged for OAuth2 access.

Bounded, idempotent, and confidence-gated​

Every sync uses a bounded overlap window plus idempotent upserts, so a re-run never double-counts a message. Just as important: only confidently project-matched events are exposed to chat and board generation. Raw cached mail stays admin/lead-only — a low-confidence match does not silently become visible context for anyone else.

What's actually blocking production use​

Three things, none of them a code change:

  1. A Google Workspace super admin must approve the restricted gmail.readonly scope for domain-wide delegation.
  2. An operator must configure an approved, narrow GMAIL_SYNC_QUERY — the sync fails closed (does nothing) when this is unset, rather than defaulting to scanning the whole mailbox.
  3. The organization must complete its security/privacy and retention review before production use. Domain-wide delegation authorization by a super admin is a necessary step, but it is not the same as documenting the business purpose, retention period, access controls, and incident owner that a restricted-scope integration needs before it goes live.

Running it​

{ "dryRun": true }
{ "confirm": true, "lookbackDays": 3 }

Scheduled/service callers do not need confirm — that flag exists for a manual, ad hoc run to require explicit intent.

Where the code lives​

  • sable-agents-demo/supabase/functions/gmail-sync/index.ts, logic.js
  • sable-agents-demo/CONNECTOR-SETUP.md — the domain-wide delegation steps (section C) that also apply to Drive and Calendar
  • sable-agents-demo/docs-site/docs/reference/environment-variables.md — GOOGLE_GMAIL_SUBJECT, GMAIL_SYNC_QUERY, GMAIL_INTERNAL_DOMAIN