Gmail

​

What It Does

• One Google account, one Cognee user. Whoever completes the consent owns the credential, and the mailbox is indexed into that user’s memory. Personal and Workspace accounts take the same path and are told apart by the hosted-domain claim (account_type: workspace or personal).
• Read-only. The requested scopes are openid email https://www.googleapis.com/auth/gmail.readonly — Cognee never modifies the mailbox.
• Its own grant. Like Google Drive, Gmail is a separate provider with its own settings and its own consent. The authorize URL does not fold its grant together with Drive’s, so disconnecting one never revokes the other.
• Opt-in by label. A new connection selects nothing. No mail is read until you choose labels and start a sync.
• Incremental and deletion-aware. The first sync backfills the selected scope and records Gmail’s historyId; later syncs fetch only what changed, and messages that are deleted, trashed or move out of scope are forgotten.

​

Prerequisites

• A Cognee backend on dev — see the version note above.
• The gmail extra installed on that backend:
  pip install "cognee[gmail]"
  
  It pulls in google-api-python-client, google-auth and google-auth-oauthlib, which the sync builds its Gmail client with. OAuth and label listing work without them, so a backend missing the extra connects fine and then fails its first sync with an ImportError.
• A Google Cloud project with the Gmail API enabled.

​

Setup

​

1. Create the Google Cloud OAuth client

​

2. Configure Cognee

​

3. Connect

curl -X POST https://<your-host>/api/v1/integrations/gmail/authorize \
  -H "Authorization: Bearer <your-cognee-token>"
# {"authorizeUrl":"https://accounts.google.com/o/oauth2/v2/auth?...&access_type=offline&prompt=consent"}

​

Choosing Labels

curl https://<your-host>/api/v1/integrations/gmail/labels \
  -H "Authorization: Bearer <your-cognee-token>"

curl -X PUT https://<your-host>/api/v1/integrations/gmail/labels \
  -H "Authorization: Bearer <your-cognee-token>" \
  -H "Content-Type: application/json" \
  -d '{"resourceIds": ["INBOX"]}'

​

Syncing and Status

curl -X POST https://<your-host>/api/v1/integrations/gmail/sync \
  -H "Authorization: Bearer <your-cognee-token>"
# {"accepted": true}

• Only the first sync reads the whole scope. Later syncs ask Gmail’s History API for changes since the stored historyId. If that cursor has expired (Gmail keeps about a week of history), the sync falls back to a full backfill.
• Transient Gmail API errors are retried — each Gmail API call retries up to 6 times before a failure counts against the sync.
• One sync per account at a time. While a sync is running, another /sync call returns the same {"accepted": true} and does nothing. The guard lives in the API process, so a deployment with several workers needs its own queue or lock.
• Nothing refreshes on its own. There are no Gmail webhooks and no built-in scheduler. Call /sync again, or from your own scheduler, to pick up new mail.

import cognee

results = await cognee.recall(
    "What did the vendor say about the renewal?",
    datasets=["gmail_jane_example_com_3f2a1b9c4d"],
)

​

Token Lifecycle and Disconnect

# Revoke the connection, keep the indexed mail
curl -X DELETE "https://<your-host>/api/v1/integrations/gmail/connection" \
  -H "Authorization: Bearer <your-cognee-token>"

# Revoke it and forget the account's gmail_… dataset as well
curl -X DELETE "https://<your-host>/api/v1/integrations/gmail/connection?delete_data=true" \
  -H "Authorization: Bearer <your-cognee-token>"

​

Limitations

• Labels intersect. There is no way to select “INBOX or Label_123” in one connection.
• No automatic refresh. /sync is the only thing that updates memory.
• One Cognee user per Google account. Connecting an account that another user already holds is refused with error_already_connected.
• gmail.readonly is a restricted scope, so public distribution needs Google’s OAuth verification.

​

Related