> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Workspace Connector

> Connect Gmail, Google Calendar and Google Drive with your own Google account

The Google Workspace connector gives the agent read-only access to your Gmail, your calendars, and your Google Drive including shared drives. Nothing can be sent, created, modified or deleted.

> [!NOTE]
>
> This is the per-user OAuth connector: you sign in with your own Google account and the agent sees exactly what you can see. If you instead want a shared bot identity that reads and writes specific Sheets, see the [Google Drive service account connector](/core/datasources/google-drive).

## Setup

1. Go to **Connectors**, open the **APIs** tab, and choose **Google Workspace**.

2. Choose who signs in:
   * **OAuth (Workspace-level)**: one Google account is connected and shared with everyone you give access to.
   * **OAuth (Per-member)**: each member who uses the connector signs in with their own Google account.

3. Choose which kinds of **access** to enable:

   | Access | Scope requested | What it unlocks |
   | - | - | - |
   | Gmail | `gmail.readonly` | Searching and reading messages, threads and attachments |
   | Calendar | `calendar.readonly` | Reading events across your calendars |
   | Drive and Sheets | `drive.readonly` | Searching and reading files, including shared drives, plus Google Sheets |

   Only the access you enable is requested, so you can connect calendar alone without granting mailbox or Drive access. Turning on more access later takes effect after the account signs in again.

4. Optionally enable **Metadata only** (see [Privacy](#privacy)).

5. Click **Connect**, sign in, and review the consent screen.

6. Click **Save**.

The connector is private to you until you share it from the **APIs** tab. With workspace-level sign-in, everyone you share it with reads the connected account, so share it only with people who should see that mailbox.

## Using it

Ask normally in any chat that can use API connectors. It composes with your warehouse and BI connectors, so questions can span both.

```
"What did Finance send me about the Q3 budget?"
"How many hours of meetings did I have last week, broken down by team?"
"Find the pricing model spreadsheet and pull the unit economics tab"
"Compare the pipeline in Snowflake to the forecast doc in Drive"
```

Search results are loaded into the Python sandbox as DataFrames, so aggregate questions about mail volume, meeting load and document activity are answered with real computation rather than by eyeballing a list.

### Shared drives

Drive searches cover My Drive, shared drives and files shared with you. Each result carries the drive it came from.

### Google Sheets

Spreadsheets are read through the Sheets API, so each worksheet arrives as its own DataFrame with its grid intact.

## Privacy

**Metadata only mode** restricts the connector to non-content fields. When it is on:

* Available: message and file ids, sender and recipient addresses, timestamps, read and attachment flags, file sizes and types, event times and durations.
* Withheld: subjects, message bodies, file names, file contents, event titles, locations and attendee lists.

Content is never requested from Google in this mode, not merely filtered after the fact.

## Troubleshooting

> **The agent says the sign-in has expired**
>
> The stored grant is no longer valid. Common causes: you changed your Google password, a Workspace administrator revoked third-party app access, you removed TextQL from your Google account permissions, or the grant sat unused for six months. Open the connector on the **APIs** tab and click **Connect** to sign in again. The connector keeps its id, so chats and agents referencing it keep working.

> **This app is blocked by your organization**
>
> Your Google Workspace administrator restricts which third-party apps may request Gmail and Drive scopes. Ask them to allow the TextQL application, or connect only Calendar, which is not a restricted scope.

> **The agent says access is not enabled**
>
> Sign-in succeeded but a scope was not granted, usually because it was unchecked on the consent screen. Sign in again and accept all the requested permissions, or turn that access off.

> **A Drive file cannot be found by id**
>
> File ids expire when a file is moved to a different drive or deleted. Re-run the document search to get a current id.

> **Searches feel incomplete**
>
> Results are bounded so a single question cannot pull an entire mailbox or drive. When more matched than were returned, the agent is told the result was truncated and should say so. Narrow the date range or add filters for full coverage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.