Repository navigation
feat(sources): Gmail and Google Workspace as an email sensor - #405
Merged
Merged
Conversation
A new "gmail" source reads a Gmail or Google Workspace mailbox, by the Gmail API (read only) or by IMAP with XOAUTH2. It signs in as a person with the Google client from Settings › Sign-in (OAuth, refresh token sealed on the source), or as a Workspace service account with domain-wide delegation. Watches follow Gmail's history ids, so a first scan of a big mailbox reads nothing and later scans read only new mail. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
Sources live at /sources; /sensors/{id} is a different thing with its own
ids, so a Gmail source signed in there landed on the wrong page.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
20 of 22 tasks
Gmail now signs in through the shared google_auth.py that Google Calendar
brought (authorized-user tokens, one access-token cache), which gains
Sign in with Google for any Google source (Gmail and Google Calendar), a
check that a sign-in allows what the source reads, and plainer refusals.
The return from Google lands on /sources?source={id}.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
Ported from #397: the journey fails now and then on main too with a 20 s timeout while a slow runner is still reading import-file's episode. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
… its own Calendar's Connect with Google (#407) brings the browser consent for Google sources; Gmail joins it in the next pull request. This one keeps the source: a connected account's token, or a Workspace service account, read through the Gmail API or over IMAP. The wording says to connect the Google account again, as Calendar's does. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q
Owner
Author
|
"Clicks and keystrokes per feature" failed on the earlier head because the graph-merge journey timed out ( Generated by Claude Code |
…-yergon # Conflicts: # CHANGELOG.md # threat-model.yaml
20 of 22 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Adeel · project thread
Description
Before: Gmail and Google Workspace mail could reach Lens only through a plain IMAP source with an app password. Workspace domains that turn app passwords off had no way in.
After: a new gmail source type reads a Gmail or Google Workspace mailbox as a sensor, through the Gmail API (read only, the default) or over IMAP with XOAUTH2 (
via). It signs in one of two ways, through the sharedgoogle_auth.pythat Google Calendar (#399) uses:tokensecret holds the account's authorized user JSON (refresh_token, client_id, client_secret), as for Google Calendar. An agent can hand over one it already has..jsonkey asservice_account_credentialsand setuserto the person it acts as. Google's refusals are explained in plain words, for example which client id an admin must allow, for which scopes, and where in the Admin console.Connecting a Google account from the browser comes with Calendar's "Connect with Google" (#407), which Gmail joins in the next PR, together with the connection dialog's Gmail option.
Labels are the source's folders, and watches, routing rules and imports work as they do for IMAP. A watch follows Gmail's history ids, so its first scan of a large mailbox reads nothing old (unless it backfills), and later scans read only what arrived. When Gmail has forgotten the history (about a week), the watch falls back to a date search.
Motivation and Context
Adeel asked for email from Gmail and Google Workspace (OAuth and service account), IMAP or API, as a sensor. Google Calendar (#399) landed the shared
google_auth.pyfirst, and Gmail signs in through it. That module gains:gmail.readonly, IMAP needshttps://mail.google.com/).The backends listing also says which types sign in to Google (
google: true). The Clicks journey's graph-merge wait is ported from #397: it times out now and then on main too.Steps to reproduce (if appropriate):
gcloud auth application-default login --client-id-file=client.json --scopes=https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/cloud-platform.POST /api/v1/sourceswith{"type": "gmail", "name": "Mail", "secrets": {"token": "<that JSON>"}}.INBOX.Types of changes
!in the title)Checklist:
tests/api/test_gmail_source.pycovers the API path, service account errors, a connected account (including IMAP over XOAUTH2, a scope it lacks, and revoked access) and agent tokens. It runs againsttests/fake_gmail.py. The full backend suite passed locally: 1091 passed, 20 skipped.docs/accordingly: processing.md (Gmail and Google Workspace), sensors.md, activity.md and README.## UnreleasedinCHANGELOG.md.Done questions (AGENTS.md)
/sources, watches, imports). An agent passes a token it already holds..envsetting.viadefaults to the API. One-click Google consent comes with feat(sources): Connect with Google for Google Calendar connections #407's button in the next PR.via,user, secrets) are edited like any other source's. Nothing is added to the setup wizard.threat-model.md/.yaml/.json.google.token,gmail.list,gmail.read). Watches read history deltas, not whole mailboxes. No model calls.storage_sourceis schemaless, and the new type only adds rows.make openapi..eml. MIT-compatible.q) filter on watches.🤖 Generated with Claude Code
https://claude.ai/code/session_01WzqrXPCMR7aJYyLPqmx41Q