Gmail connection
In plain words: Reach: Gmail connection
A proposed profile for connecting one Gmail or Google Workspace mailbox, choosing what Reach may read, and preparing replies, including Google's registration, consent and verification hurdles.
- 1Each mailbox is a separate connection; two employers' mail are never combined.
- 2Registration differs for own Workspace, personal Gmail, a client firm, or a shared public app (which needs verification).
- 3Mailbox writes like labels or drafts are separate effects from sending, each needing its own handling.
Designed Candidate profile; no OAuth flow or live Gmail access.
Words on this page, decoded click one for its card
The operator connects one mailbox, selects the mail Reach may inspect, and prepares a reply from that account. Connecting a second employer creates another connection, not a shared inbox or permission to combine the two companies' ContextBriefing Pack.
This candidate profile, reach.gmail.correspondence@1, belongs to the
successor study. Gmail-enabled personal accounts and Workspace accounts can use the API;
Business Standard is not a prerequisite. Google's prerequisites
require a Cloud project and Gmail access, not that subscription.
First registration and customer friction
| Use | Proposed registration | Operational consequence |
|---|---|---|
| Operator's own Workspace | Organization-owned Cloud project, Internal audience, same-organization users. | Internal verification exception; the administrator still controls access. |
| Operator's personal Gmail | Personal-use OAuth project, External audience and production publishing state. | Personal-use exception may apply; unverified warning/user limits remain. Testing is a development state, not durable unattended operation. |
| One client firm's internal deployment | Its organization-owned project and Internal audience for its own users. | Repeat registration per customer, with separate custody. Self-hosting alone creates no exception. |
| One shared application serving unrelated firms or the public | Publisher-owned External application. | Plan brand/scope verification and, where restricted data is accessed through servers, the applicable independent security assessment and recurring review. |
The restricted-scope review rules define the exemptions and annual assessment obligation. Confirm applicability against the actual deployment/data path before promising a commercial onboarding flow or cost. Buying Workspace does not verify a publisher's application for other companies.
External Testing grants with Gmail scopes ordinarily expire after seven days. Google's current app-state guidance documents an organization-local override when its Workspace administrator marks an app Trusted. That is an admin-governed pilot option, not public verification or an Internal audience spanning unrelated firms. A verified app can still be blocked by an administrator.
Use a dedicated agent-workflow OAuth client. Google's client guidance separates AI-agent and ordinary interactive clients when both coexist. The REST quickstart makes the agent checkbox optional; the announced MCP enforcement is not a universal REST requirement.
Consent and capability closure
The server authorization-code flow requests offline access, uses the exact registered callback,
and keeps refresh tokens with the credential owner. Ordinary token refresh needs no user click.
Retain an existing refresh token when a later response omits it. Invalid/revoked grants stop work
and enter REAUTH_REQUIRED; new permissions require explicit incremental authorization.
Offline OAuth
Request minimal openid/email identity scopes as well as the selected Gmail scopes. Validate the
ID token's issuer, audience, expiry and flow binding; retain (issuer, sub) as the account identity,
with email only as display/routing data. Mail headers cannot establish that binding.
Google identity
| Requested capability | Provider scope | Local restriction |
|---|---|---|
| Search and read selected messages/threads | gmail.readonly |
Restricted scope; query/label selection is a Reach boundary, not provider-enforced isolation within the mailbox. |
| Save drafts and send | gmail.compose |
Restricted scope; it already permits sending. Review-only mode must be enforced locally. |
| Optional labels, archive and read-state changes with read/draft/send | gmail.modify |
Restricted and broader than those named actions; replace narrower grants only when required. Exclude trash/settings/destructive operations locally. |
| A separate send-only integration | gmail.send |
Sensitive scope; cannot serve an inbox-reading agent. |
Avoid full https://mail.google.com/ access. Google's scope table
is the authority for classification and scope coverage. Calendar, Drive and mailbox administrative
settings are later separately authorized capabilities.
Mailbox writes are separate effects
Saving a draft is already an external effect: Google receives the body even though no recipient
does. The proposed ReachMailboxMutationIntent@1 and ReachMailboxMutationReceipt@1 would account
for that effect by binding one connection, operation, exact message/draft ids, MIME or label delta,
preparation/observation, authorization, expiry, effect identity and fenced attempt. Apply the same
durable outbox states and current byte-time disclosure checks used for delivery. Authority to
create a draft neither consumes nor implies authority to send it.
The first draft operation creates a Reach-owned snapshot and retains the returned draft id.
Ambiguous creation remains UNKNOWN until matching draft content/correlation is reconciled;
never retry creation merely because one list call did not find it. Updates to human/shared drafts
are deferred: Gmail read-before-write alone supplies no atomic compare-and-swap guarantee.
Revised preparation stays local or creates a separately admitted snapshot, without overwriting an
existing draft. The first send path submits sealed MIME directly rather than mutable draft bytes.
Optional label/read/archive changes bind the exact message set and add/remove label ids. Repeated application is eligible only when that adapter contract proves the same desired-state operation safe and current authority still admits it. Readback can establish observed desired state, not exclusive authorship of a change. Unknown or conflicting observations stop for reconciliation; trash and deletion remain excluded. Message label changes
Synchronization and sending
Begin with a bounded initial synchronization, persist a mailbox history cursor, and use outbound
incremental polling to follow subsequent changes. A later Pub/Sub option requires a topic in the
calling project, a grant for Gmail publication, and either authenticated push or outbound pull.
Renew watch before expiration (Google recommends daily; at least every seven days).
A notification only wakes synchronization; it contains neither the message contents nor a complete event history. Persist admitted changes and finish pagination before advancing the processed cursor. Repeated or out-of-order notifications therefore cannot create new sends. Push contract
Expired Gmail history returns 404. Rebuild the purpose-bounded projection with a new full sync; do not replay every rediscovered message as a fresh request. A new watch baseline cannot overwrite an unprocessed cursor. Synchronization
Before review or standing-policy admission, freeze the canonical MIME, sender/alias, recipients, reply headers and body. Check that the alias is eligible; it shares the mailbox's limits and provides no separate identity grant.
Gmail's send API documents no idempotency key, so retain an application effect id and RFC Message-ID
for correlation, followed by the returned Gmail message id when available. If submission times
out, keep UNKNOWN while inspecting Sent mail. Matching author, destination, bytes and correlation
can support reconciliation. A missing result in one read cannot prove non-delivery. A vanished
draft alone is insufficient evidence of the send outcome, and provider acceptance still does not
establish final delivery.
Send API,
draft lifecycle,
delivery errors
Limit concurrency and budget per mailbox and project. Respect backoff, provider retry timing and daily sending limits independently. As checked on 2026-10-21, new-project defaults are 6,000 quota units/minute/user/project and 1,200,000/minute/project; sending costs 100 units. Some older projects retain prior quotas. Read the actual project's allocation rather than baking those numbers into the application contract. Current API quotas
Privacy and maintenance
Render bounded plain text from untrusted MIME/HTML without fetching remote images. Treat From,
Reply-To, quoted instructions and authentication headers as attributed evidence, never WardSecurity Desk
identity. A sender can request an action but cannot grant private-record access or change the
recipient policy. Attachment parsing/download is a later explicit artifact/quarantine path.
Disclose any hosted model transfer and admit it under the user's purpose and privacy policy. Workspace data cannot become general model-training material; current provider policy also requires prompt-injection protection. Workspace data policy
Routine releases retain the client/grant/cursor/outbox identities. Scope or material consent-screen changes may require new authorization or verification; automatic refresh and watch renewal belong to the service. Approved-app changes