# Gmail > Gmail: what the collector reads, how to connect it, its permissions, its certification by Atlantic Agentic Labs and its security posture. Built, not certified Built and tested against recorded and synthetic responses (version 1.0.0, 10 November 2026). Not yet run against the vendor's sandbox or a client environment. Reads the messages carrying one Gmail label that you name, in a mailbox you name, so agents can answer from the correspondence a team filed there. The module also carries one tool that writes: a draft, never a send, refused unless a named person has approved it. ## At a glance | Collector | Gmail, version `1.0.0` | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Reads | Google: Gmail ([the vendor's documentation](https://developers.google.com/gmail/api/guides)) | | Family | Communication | | Kind | Mail | | Ways to connect | Service account, OAuth approval | | Scopes | - Read: `https://www.googleapis.com/auth/gmail.readonly` - Read_write: `https://www.googleapis.com/auth/gmail.compose` | | Read only | No | | Vendor's API can move money | No | | Personal data | Contact, Identity, Content | | Hosts it may contact | `gmail.googleapis.com`, `mail.google.com` | | Vendor API versions | Gmail API v1 | | Lowest engine version | `0.45.0` | ## What it reads - Messages carrying the label you name (`mailbox_label`) as text: the plain-text part, or the HTML part with its tags removed, with subject, correspondents and date. - The cursor is the mailbox history id, kept with the ids of the messages written. A message that loses the label or is deleted is withdrawn. - Gmail keeps history for about a week. When the stored id has expired the API answers 404 and the collector lists the label again in full and withdraws what is no longer there, rather than staying broken until someone clears the cursor. - Never read: anything outside the label, and attachments. A document that matters belongs in a folder or drive the engine syncs, where it has an owner and a version. ## How to connect 1. Create a service account and, in your Google Workspace admin console, grant its client ID domain-wide delegation for `https://www.googleapis.com/auth/gmail.readonly` and no other scope. 2. In LightHouse, open **Connectors**, choose **Gmail**, name the **Read as** person, the **Mailbox label** (a whole mailbox cannot be asked for), the label for the corpus and how often to read, and attach the service-account key. LightHouse asks Google what the minted token carries and refuses a key whose token carries more than `gmail.readonly`. 3. In code, give the deployment an OAuth access token with the `gmail.readonly` scope as `GMAIL_TOKEN` and add a `kind: gmail` source card with `mailbox_label`, `label` and `requires`. ## Permissions The reader needs `https://www.googleapis.com/auth/gmail.readonly` only, and sends only `GET` requests to `gmail.googleapis.com`; nothing in a pull calls a send or drafts endpoint. Its read-only test proves it on every change. The module also holds `create_draft`, which makes one Gmail draft for a person to review and send. It is the only write, it posts to `/gmail/v1/users/me/drafts`, it can never send, and it is refused before any token is read unless a named person’s approval is in hand, the agent’s card is `effect: external` and lists the tool in `effect_tools`, and the tool policy allows it (never at autonomy 0). A token that can create drafts needs a wider scope, such as `gmail.compose`; the LightHouse connection asks for `gmail.readonly` only, so drafts need a token you mint yourself. ## Limits - You must name the label; a whole mailbox is never the default, and a label that does not exist is an error. - Attachments are not read. - Messages are read as text; formatting and inline images are lost. - The access token lasts about an hour; the collector holds no refresh token. ## Data handling - Message text is copied into the deployment’s corpus under the source’s `label`, normally a confidential one. Mail names people and holds personal data of any kind. - The token stays in your secret store, is never written to logs or run notes, and is sent only to Google. - Each draft is logged as an event with the agent, the approving person’s name and the count of recipients, never the text. - Nothing leaves the deployment: only counts reach LightHouse. ## Troubleshooting | What you see | What it means | What to do | | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------- | | `name the mailbox label to read; a whole mailbox is never the default` | `mailbox_label` is empty | Name the label | | `the mailbox has no label` | The label does not exist in that mailbox | Check its name (case and slashes) and the Read as person | | `credential variable 'GMAIL_TOKEN' is not set` | No access token in the environment | Mint a token with the `gmail.readonly` scope and set it | | `not a Gmail message id` | A message id with characters other than letters and digits was returned or given | Report it; this should not happen | | `a draft needs a named person's approval` | `create_draft` was called without an approved decision | Approve the card in LightHouse first | | `list aal__gmail__create_draft in effect_tools on an external card` | The agent’s card does not declare the draft as an external effect | Add it to `effect_tools` on an `effect: external` card | | `POST ... /drafts: HTTP 403` | The token has no scope that allows drafts | Mint a token with `gmail.compose` | | Read succeeded, 0 written | Nothing changed since the history id | Nothing to do | ## Certification Each entry is a run by Atlantic Agentic Labs, newest first. Only a run against the vendor’s sandbox or a client environment certifies a collector; a certification lasts six months, or less if the vendor publishes an API version the collector does not list. See [How collectors are certified](/collectors/certification/). | Date | Collector | Engine | Vendor API | Method | Expires | | ---------------- | --------- | -------- | ------------ | ----------------------------------- | -------------- | | 10 November 2026 | `1.0.0` | `0.45.0` | Gmail API v1 | Fixtures only: built, not certified | Not applicable | ## Security posture From the collector’s last scan on the default branch. What each line means, and what blocks a release: [Security posture](/collectors/security/). | Last scanned | 10 November 2026 | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Critical findings | 0 | | High findings | 0 | | Medium findings | 0 | | Low findings | 0 | | Info findings | 0 | | Release blocked | No | | Network allow-list check | Pass | | Read-only behavioural test | Pass | | SBOM (CycloneDX) | Produced | | Dependency licences | Pass | | Scanners | bandit 1.9.4, semgrep 1.181.1, pip-audit 2.10.1, osv-scanner 2.7.0, cyclonedx-py 7.5.0, pip-licenses 5.5.5, gitleaks repository job aal-secrets, hosts_check tools/hosts_check.py, read-only test pytest -m read_only | Source: https://docs.atlanticagenticlabs.com/collectors/catalogue/gmail/