Skip to main content
The Gmail and Outlook Mail connectors let the agent search and read messages in a user’s own mailbox. Each user connects their own account; the agent then answers questions from what is in that inbox — a contract sent last quarter, the thread where a number was agreed, the vendor’s latest invoice.
Both connectors are part of the Enterprise Edition.
These connectors are not the Email channel. The Email channel gives the Bag of words analyst its own mailbox so it can send answers and receive questions — one shared address, configured once by an admin. These connectors do the opposite: they let the agent read your mailbox as data. The two are configured separately and can be used together or independently.

​
How it works

Both connectors are per-user (catalog_ownership: per_user) and read-only. There is no shared catalog and no admin-side message list — a mailbox is searched and read live, per user, at question time. That is why neither connector has any config fields. The agent gets mail-shaped tools rather than file tools: Only reading and searching are supported. Neither connector can send, draft, label, or delete mail. See User context and per-user data for how per-user connections behave in a conversation.

​
Gmail

​
Before you start

  • A Google Cloud project you can administer, with the Gmail API enabled.
  • Access to the project’s OAuth consent screen (choose Internal for a Workspace organization).
  • Your Bag of words base URL, for the redirect URI.

​
Step 1 — Create a Google OAuth client

1

Enable the Gmail API

Google Cloud console → APIs & Services → Library → enable the Gmail API.
2

Create the OAuth client

APIs & Services → Credentials → Create credentials → OAuth client ID, application type Web application.
3

Add the redirect URI

Under Authorized redirect URIs:
Scopes requested at sign-in:

​
Authentication modes

Google OAuth Client — oauth_app (scopes: system and user) Sign in with Google — oauth (scope: user, no fields). Each user clicks Connect and consents; the agent reads only that user’s mailbox.

​
Outlook Mail

​
Before you start

  • A Microsoft Entra ID app registration with a client secret.
  • An administrator who can grant admin consent for the Graph permissions.
  • Your Bag of words base URL, for the redirect URI.

​
Step 1 — Register an Entra ID application

1

Create the app registration

Azure Portal → Microsoft Entra ID → App registrations → New registration. Copy the Directory (tenant) ID and Application (client) ID from the Overview page.
2

Create a client secret

Certificates & secrets → New client secret. Copy the value immediately.
3

Add the Graph permissions

API permissions → Microsoft Graph → delegated Mail.Read, User.Read, openid, profile, offline_access. Then click Grant admin consent.
4

Add the redirect URI

Authentication → Add a platform → Web:
If you already registered an app for SharePoint and OneDrive, you can reuse it — just add the Mail.Read delegated permission and grant consent again.

​
Authentication modes

Entra ID App (Service Principal) — service_principal (scopes: system and user) Sign in with Microsoft — oauth (scope: user, no fields). Each user completes the Microsoft authorization-code flow; Graph then serves /me/messages for that user only. See Authentication and access.

​
Connect in Bag of words

Go to Data Sources → Add data source and choose Gmail or Outlook Mail. Enter the admin credential above and save — there is nothing else to configure. Each user then clicks Connect on the connection to sign in with their own account before the agent can search their mail.

​
Troubleshooting

The user has not completed Connect. These connectors have no shared credential to fall back on — a mailbox is only reachable after its owner signs in.
Both providers must have https://<your-bow-host>/api/connections/oauth/callback registered exactly, matching your Bag of words base URL.
Mail.Read was not granted or not admin-consented. Check API permissions on the app registration.
offline_access (Microsoft) is missing from the granted permissions, so no refresh token is issued.