Outlook Connector

Use this page when you need the Microsoft-side setup details for the Outlook 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 microsoft
• Callback URI examples:
  • http://localhost:3001/api/auth/oauth2/callback/microsoft
  • https://auth.example.com/api/auth/oauth2/callback/microsoft
• Setup console URL:
  • Microsoft Entra app registrations
• Required connector scopes:
  • Mail.Read

Provider-Specific Gotchas

• Outlook is live-preferred in this repo. Indexed sync is implemented, but the live mailbox search path is the primary operator expectation.
• If indexed mode is enabled, eligible Outlook content is stored as extracted chunk text and vectors for retrieval. Keeping Outlook live-only avoids embedding sync and indexed artifact retention.
• Outlook and OneDrive share the same connector auth binding. If OneDrive was linked first, reconnect the linked microsoft account after adding Outlook so Mail.Read is present.
• Keep the app registration aligned with the tenant you expect to authorize. The repo intentionally uses the generic Microsoft OAuth path for tenant-scoped connector auth instead of a second social-provider path.
• The same signed-in user may link more than one Microsoft account. The shared connector configure flow remains the canonical chooser after callback, even though Microsoft also receives an explicit select_account prompt during OAuth.

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

• Register an application in Microsoft Entra ID
• Microsoft Graph permissions reference