# Google Workspace: how to read it into Maplith

*Communication · also known as Gmail, Google Drive, G Suite · last checked 2026-10-14 · recipe `maplith://systems/google-workspace`*

Google Workspace holds the company's mail and documents: who asks for what, how requests are answered and handed on, and the procedures written down in Docs and Sheets. Maplith reads them to find the recurring processes and write a playbook for each, never to keep the mail.

## Best path

**Recommended: your agent fetches it.** Many assistants already reach Gmail and Drive, and a first map needs a few weeks of a few labels and the folders with procedures. For a daily refresh, Maplith's own Google connector reads the labels and folders a rule selects, once it is switched on for the workspace.

Try the paths in this order (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. Connectors a vendor or client page confirms: Gmail and Google Drive connectors in Claude; Google Drive connector in ChatGPT. The agent reads the recent mail of the labels its human names, a few weeks each, and the documents of the folders that describe how work is done, and leaves out anything private or personal. It only reads; it should not send, label or edit.
2. **Maplith reads an MCP server your human already has.** No official MCP server confirmed. The assistants' own connectors are the way an agent reads Gmail and Drive. Maplith reads only a server that serves MCP resources and takes a token a person types under Data sources › Systems in the Maplith app, such as the customer-run template for a database (ADR-0028).
3. **Export files**, the fallback that always works: see *Export steps* below.
4. **Maplith's own integration** (built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours): see *Maplith's integration* below.

## Datasets that make a good map

| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Mail by label | One message in a chosen label: when, from and to whom (addresses, which the masking tries to mask), its subject and body, and the thread it belongs to. | label, message id, thread id, date | The orders, cases and invoices the messages name; the processes the map finds in other systems by the same reference. |
| Documents | One Google Doc, Sheet or text file in a chosen folder: its name, when it changed, and its text or rows. | file id, folder, name, modified time | The processes the procedures describe; the systems they name. |
| Notices from other systems | One message a system sent (an invoice, a report, an alert), recognised by its sender. | sender domain, subject, date | The system that sent it, which often is a system not yet shared with Maplith. |

Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: your human decides what goes in.

## Read-only access

**Who usually has the rights:** A Google Workspace super administrator, who creates an Internal OAuth client in the organisation's Google Cloud project, and the account whose mail and Drive are read, who consents once.

**For the key your own agent's client uses, choose only these read permissions:** `gmail.readonly`, `drive.readonly`

**Where to click:**

1. In the Google Cloud console of the organisation, create a project or choose one, and enable the Gmail API and the Google Drive API
2. Under the OAuth consent screen, choose the user type Internal, so only accounts of the organisation can consent and no Google review is needed
3. Add the scopes gmail.readonly and drive.readonly, and nothing else
4. Create an OAuth client of type Web application, and keep its client id and secret for the next step, never in a chat

A key or token made here stays in the tool that reads the system for your human, never in a chat. Maplith asks for one only under Data sources › Systems in the app: for an MCP server it can read, or for its own integration below.

## Export steps

**Format:** MBOX for mail and the documents' own formats for Drive, from Google Takeout · **Date range:** The last 3 months

1. Open Google Takeout with the account whose mail is to be read
2. Choose Mail with only the labels that carry work, and Drive with only the folders that describe how work is done
3. Create the export and download it when Google sends the link
4. Remove anything private or personal before uploading the files under Data sources › Scans

## Volume hint

**About 500–10,000 messages a month** (an estimate). Estimate for a small company, not a measured figure: notices from other systems add most of the volume.

Every row an agent reads passes through its context, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, prefer an MCP server or an export over fetching through the chat.

## Maplith's integration

**Status:** built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours.

**How to connect:**

1. Create the Internal OAuth client with the two read-only scopes, as under Read-only access above
2. In Maplith, open Data sources › Systems and click Connect Google Workspace
3. Give the client id and secret there, and sign in with the account whose mail and Drive are read to consent; Maplith seals the result and never shows it again
4. Click Test connection to see which labels and folders it will read and which it leaves out

**The permissions it needs, and why:**

- `gmail.readonly`: reads the messages of the labels the rule selects; it cannot send, delete or change a message
- `drive.readonly`: reads the documents of the folders the rule selects; it cannot change or share a file

**What it reads:**

- Mail in the selected labels within the scan window, as a mailbox export the build reads and deletes with the run
- Google Docs as text, Google Sheets as CSV, and plain text files in the selected folders, within size limits
- What reaches the map: the labels and folders as sources, the processes the mail and documents show and the systems they name; playbooks describe the process, never quote a message

**What it never reads or does:**

- Spam, trash or drafts, a label named Private or Personal, or a file in a folder so named or in any folder below one
- Mail from, to or copied to a domain the rule denies, or a file owned by one: dropped before it is written, and only counted
- Sending, labelling, deleting or changing anything in Gmail or Drive

**Choosing what is read:** Maplith reads the inbox and sent mail and the documents changed within the scan window, except the labels and folders its rule leaves out (a folder with everything below it) and the denied domains. When the rule names a shared drive or folders, it reads documents only there and in their subfolders. A person changes the labels, the folders and the denied domains under Data sources › Systems; that choice is theirs from then on.

## What Maplith sets up once it is connected

Maplith builds these itself; a person corrects them, and never has to approve them first (ADR-0038). If the system is disconnected, Maplith takes the playbooks it set up and nobody changed out of use, and puts them back when the system is connected again; a playbook a person changed stays as they left it.

**Signals:**

| Kind | Delivery | When |
|---|---|---|
| `link_dead` | poll | the daily probe finds the consent withdrawn, the client deleted or a scope missing |
| `structure_changed` | poll | the connection offers at least a quarter more or fewer resources than at the last check |
| `process_silent` | poll | a recurring process the map found in the mail has not happened within its usual interval |
| `finding_added` | poll | the mail names a system the map does not have, or a hand-off that happens out of sight of every shared system |

**Checks:**

- **Connection probe** (every 12 hours): checks that the consent still holds and the labels and folders are readable, never a message
- **Selection rule** (every scan): states which labels and folders are read and which are left out, and how many items the denied domains dropped, on every scan

**Suggested playbooks:**

- **Reconnect Google Workspace.** Starts when the Google connection's link_dead signal is raised. Steps: Open Data sources › Systems and run Test connection to read the reason; If the consent was withdrawn or expired, connect again and sign in with the same account; If a scope is missing, add it to the OAuth client and connect again; Run Test connection again and record what was done.
- **Share the system the mail names.** Starts when a finding says the mail names a system the map does not have. Steps: Read the finding: which system, and in which label it shows up; Ask the system's owner whether it may be shared with Maplith; Connect it, or upload an export, as that system's guide describes; Resolve the finding with what was decided.

**Schedules:**

- **Read Google Workspace** (with the workspace's scan schedule (daily or weekly)): the playbooks and the processes stay current with how the work is actually done

**What setup integrity expects:**

- The Google connection exists and its last probe succeeded
- The mail and drive sources have an owner and a refresh cadence (Maplith states them from the workspace owner and the scan schedule; a person corrects them)
- Each suggested playbook exists, or a person removed it

## Always

- Read-only, and never a credential sent to Maplith through the chat.
- The same recent period, a few months, from every system.
- Your human decides what goes in.

## Sources

Written from the vendor's public documentation, last checked 2026-10-14:

- https://developers.google.com/workspace/gmail/api/auth/scopes
- https://developers.google.com/workspace/drive/api/guides/api-specific-auth
- https://support.google.com/cloud/answer/10311615
- https://support.google.com/accounts/answer/3024190