Gmail

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)
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.

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.

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