Unified connector for Gmail, Google Drive, and Google Calendar.

Google Workspace Connector

A single connector that ingests Gmail messages, Drive documents, and Calendar events into CortexDB. Domain-wide delegation gives the connector access to all configured users; OAuth alternatively scopes it to one user.

Info

Two ways to run this connector:

  • Run it yourself (Free + paid) — pip install 'cortexdb-connectors[google-workspace]' then cortexdb-sync sync google-workspace. The connector reads your token from ~/.cortexdb/state.json (written by cortexdb init) or from env vars.
  • Managed sync (Starter and up) — CortexDB runs the connector as a worker on its infrastructure. Configure it once from your dashboard; CortexDB handles webhook registration, retries, backfill, and idempotency.

1. Prepare credentials in Google Cloud

  1. Google Cloud Console → APIs & Services → enable Gmail, Drive, and Calendar APIs.
  2. Create a service account; generate a JSON key.
  3. Admin console → Security → API controls → Manage Domain Wide Delegation. Add the service account's client ID with these scopes:
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/drive.readonly
    • https://www.googleapis.com/auth/calendar.readonly

2. Configure in your CortexDB dashboard

  1. Sign in at cortexdb.ai/login.
  2. Settings → Connectors → Add Connector → Google Workspace.
  3. Upload the service-account JSON key.
  4. Enter the delegated user emails to sync (comma-separated, e.g. [email protected], [email protected]).
  5. Pick which sources to enable: Gmail, Drive, Calendar.
  6. Set the scope template. Default: org:<your-org>/source:google/user:{user_email}.
  7. Click Start sync.

What gets written

SourceEventModality
GmailIncoming messageconversation (role=user)
GmailOutgoing messageconversation (role=assistant if drafted by an agent, else user)
DriveDoc created/editeddocument
DriveCommentconversation; preceded_by links to doc
CalendarEvent created/updatedobservation; attendees as labels
CalendarRecording / Meet transcriptconversation per speaker

idempotency_key shapes:

  • Gmail: gmail:<user>:<message_id>:<history_id>
  • Drive: drive:<file_id>:<modified_time>
  • Calendar: gcal:<calendar_id>:<event_id>:<updated>

Run it yourself

If you'd rather host the connector yourself instead of using CortexDB's managed worker, every connector ships in the cortexdb-connectors PyPI package:

pip install 'cortexdb-connectors[google-workspace]'

# Step 1: get a CortexDB token + actor (one-time, free tier)
pip install cortexdb-cli
cortexdb init

# Step 2: supply the connector's third-party credentials
export GW_SERVICE_ACCOUNT_KEY=...                # required
export GW_DELEGATED_USER=...                # required

# Step 3: one-shot sync, or `watch` for a poll loop
cortexdb-sync sync google-workspace
cortexdb-sync watch google-workspace --interval 60

cortexdb-sync reads your CortexDB token + actor from ~/.cortexdb/state.json automatically. Cursor state is persisted in ~/.cortexdb/connectors-state.json, so re-running picks up where the last cycle left off.

See also