Gmail Sensor

What it ingests

Mailbox messages — subject, body, sender, and recipients — from every Workspace user in the org. Coverage fans out across every member by impersonating each user, so a single subject is not required for ingestion.

The same mail in two inboxes (sender and recipient both in the org) is one Message entity, keyed on the RFC 822 Message-ID. Spam, trash, and drafts are skipped.

A first poll seeds each mailbox's Gmail history id without emitting. Historical ingest is the worker's one-shot Backfill (SENSOR_BACKFILL_SINCE, default 72h). Incremental ticks use the History API so a busy mailbox is not re-listed newest-first every tick.

The mapper stays structured and low-volume: one Message entity per mail, Person AUTHORED from the sender, recipients as identity hints. No LLM pass by default — mail volume is high.

Microsoft Outlook email is a separate sensor, not a mode of this type.

Credential

References a google_service_account_json credential by id — the same type Meet, Drive, and Calendar already use. No new service account. The secret is the full service-account key JSON. Leave it blank to fall back to application-default credentials (ADC) for local/dev use without impersonation.

The existing domain-wide delegation grant must include:

https://www.googleapis.com/auth/gmail.readonly

Test connection names this scope if it is missing, rather than returning a generic 403.

curl -sS -X POST https://your-corveil-host/api/credentials \
  -H "Authorization: Bearer <admin>" -H "Content-Type: application/json" \
  -d @- <<'JSON'
{ "type": "google_service_account_json", "name": "acme-workspace-sa",
  "secret": "{\"type\":\"service_account\", ... }" }
JSON

If you already created this credential for Meet, Drive, or Calendar, reuse it. Add gmail.readonly to the existing DWD grant in the Workspace Admin console — do not mint a second key.

Config fields

All config fields are optional — with a DWD service account and no config, the source fans out across every org member.

Key	Notes
impersonate_subject	Connection-test user only. A Workspace user Test connection impersonates to probe Gmail reachability. Not needed for ingestion.
member_allowlist	Comma-separated Workspace users. Restricts fan-out to these members (staged rollout / testing).
workspace_domains	Comma-separated domains. Only members whose email domain matches are impersonated; others are skipped.
query	Extra Gmail search operators AND-ed onto -in:spam -in:trash -in:drafts. Example: from:customer.com -category:promotions.
lookback_days	How far back the one-shot Backfill reads. Defaults to 7. Incremental polls use the History API and are not capped by this window.
poll_overlap_minutes	Minutes to re-scan before the last cursor on a History-expired fallback list. Defaults to 30. Unused while History ids are valid.

Provider-side setup

1. Reuse the service account already used for Meet / Drive / Calendar, or create one and download its key JSON.
2. Enable the Gmail API on the project.
3. In the Workspace Admin console, enable domain-wide delegation for the service account and authorize https://www.googleapis.com/auth/gmail.readonly on the existing client (alongside the Meet / Drive / Calendar readonly scopes).

Wire-up

POST /api/sensors

{
  "sensor_type": "gmail",
  "name": "Acme Gmail",
  "config": {},
  "credentials": { "service_account_json": "<google_service_account_json credential id>" }
}

Staged rollout to two users first:

{
  "sensor_type": "gmail",
  "name": "Acme Gmail (pilot)",
  "config": { "member_allowlist": "alice@acme.com, bob@acme.com" },
  "credentials": { "service_account_json": "<credential id>" }
}

Verify

Run Test connection. With a service account it impersonates impersonate_subject to probe Gmail reachability; if that subject is unset it only checks that the key parses. A missing gmail.readonly grant fails with a named scope error.

Once polling, newly delivered mail appears as Message entities. A sender or recipient already in the graph (Slack, GitHub, Meet) canonicalizes onto those same Person entities by email.