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.