Skip to content

gmail

diapason.connectors.gmail

Gmail connector — bulk email sync via the Gmail REST API.

Uses OAuth 2.0 tokens stored locally (see :mod:diapason.connectors.oauth). All network calls are isolated in module-level functions (_gmail_api_*) to make them trivially mockable in tests.

GmailConnector

Bases: BaseConnector

Connector that syncs emails from Gmail via the REST API.

Authentication is handled through Google OAuth 2.0. Tokens are stored locally in a JSON credentials file.

Parameters

credentials_path: Path to the JSON file where OAuth tokens are stored. Defaults to ~/.diapason/connectors/gmail.json.

archive_message(msg_id)

Archive a message by removing the INBOX label.

auth_url()

Return a Google OAuth consent URL for the shared Google scopes.

Without a stored client_id, this returns the Cloud Console credentials page rather than a consent URL — same behaviour as the three sibling Google connectors. A consent URL carrying an empty client_id is not a degraded URL, it is a broken one: Google answers The OAuth client was not found, and the user goes looking for the fault on their own side.

delete_message(msg_id)

Move a message to Trash (recoverable for 30 days).

disconnect()

Delete the stored credentials file.

handle_callback(code)

Handle the OAuth callback by persisting the authorization code.

In a full implementation this would exchange the code for tokens. For now the code is saved directly as the token value.

is_connected()

Return True if a credentials file with a valid access token exists.

The previous "any non-empty dict counts" check returned True for files containing only client_id/client_secret (no actual OAuth token), which made diapason connect gmail short-circuit with "already connected" before any OAuth flow ran.

mcp_tools()

Expose three MCP tool specs for real-time Gmail queries.

sync(*, since=None, cursor=None, query_extra='')

Yield :class:Document objects for Gmail messages.

Paginates through the messages.list API and fetches each message's full payload to extract headers and body.

Parameters

since: When provided, only messages received after this timestamp are returned. Translated to a Gmail after:<epoch> search query. cursor: nextPageToken from a previous sync to resume pagination. query_extra: Additional Gmail search operators appended to the base query, e.g. "is:unread" to restrict to unread messages only.

sync_status()

Return sync progress from the most recent :meth:sync call.