Gmail Connector

Use this page when you need the Google-side setup details for the Gmail connector. For shared connector behavior, start with Connectors Overview and Provider Auth And Setup.

Runtime Shape

• Implemented modes: live by default, optional indexed
• Auth binding: Better Auth generic OAuth provider id google
• Callback URI examples:
  • http://localhost:3001/api/auth/oauth2/callback/google
  • https://auth.example.com/api/auth/oauth2/callback/google
• Setup console URL:
  • Google Cloud Console credentials
• Required connector scopes:
  • https://www.googleapis.com/auth/gmail.readonly

Provider-Specific Gotchas

• Gmail is live-preferred in this repo, but indexed sync is also implemented. Missing refresh-token coverage will break sync even if the first interactive link looked successful.
• If indexed mode is enabled, eligible Gmail content is stored as extracted chunk text and vectors for retrieval. Keeping Gmail live-only avoids embedding sync and indexed artifact retention.
• Gmail and Google Drive share the same connector auth binding. Reauthorization under an existing linked google account requests the full scope set needed by sibling Google connectors under that account, so adding Gmail after Drive preserves Drive access while adding mailbox access.
• The shared Google connector auth path forces account selection and consent. Keep that behavior; otherwise the browser can silently reuse the wrong Google account.

Canonical Sources

• packages/domain/src/connectors/connectorRegistry.ts
• apps/auth/src/genericOAuthProviders.ts
• apps/api/src/connectors/oauthTokenClient.ts
• docs/features/connectors/spec.md

Official Docs

• Gmail auth scopes