Gmail and Google Workspace

If your operator has already connected Gmail, start with Connect your inbox; this page covers server-side Google setup and its restrictions.

Use the gmail preset for a consumer Gmail or Gmail-enabled Google Workspace mailbox, including a custom-domain address. This milestone targets personal/self-hosted and genuine internal Workspace use. It does not create Google credentials, run consent, change administrator settings, or establish live-account eligibility.

The preset uses imap.gmail.com:993 with implicit TLS and smtp.gmail.com:465 with implicit TLS. Port 587 is supported with mandatory STARTTLS. Use the complete mailbox address. Gmail endpoints are pinned; custom host overrides and incompatible auth configuration are rejected. Google protocol settings, Workspace SMTP settings

Two separate OAuth systems

• MCP OAuth authenticates a client to Angelos using its configured issuer, resource URL, subject allowlist, and mail.read/mail.write/mail.send scopes.
• Google mailbox OAuth authorizes the server to access its one configured Gmail mailbox. Its credentials remain server-side and never appear in MCP arguments or results.

Google’s IMAP/SMTP XOAUTH2 scope is exactly https://mail.google.com/. Gmail API scopes such as gmail.readonly and gmail.send are not substitutes for that protocol scope. The Google grant is broad even when the MCP client has only read permission; Angelos still enforces its own operation scopes and disabled-by-default write/send gates. A Google mailbox access token is not an Angelos MCP token. Google XOAUTH2 requirements

Server configuration

Provision secrets directly through the server’s secret manager, never in a repository, chat, screenshot, or token-bearing link.

MAIL_PROVIDER=gmail
MAIL_AUTH_MODE=google_oauth2
MAIL_USERNAME=person@example.com
MAIL_FROM=person@example.com
GOOGLE_CLIENT_ID=your-web-application-client-id
GOOGLE_CLIENT_SECRET=
GOOGLE_REFRESH_TOKEN=

The secret fields above are deliberately blank; supply the owner-provisioned values securely. Remove MAIL_PASSWORD when using Google OAuth. google_oauth2 is the Gmail default; it must have a complete matching client ID, client secret, and refresh token. For SMTP STARTTLS, also set SMTP_PORT=587 and SMTP_TLS_MODE=starttls.

MAIL_FROM should be the authenticated mailbox or an already authorized Google send-as alias. Angelos does not create aliases or change Google sender settings. MAIL_ALIASES only excludes your own addresses from derived replies; it does not grant sender authority. Google alias setup

The server refreshes access tokens at Google’s fixed HTTPS token endpoint, caches them only within the backend instance, and honors returned expiry. Refresh requests are bounded, redirects are denied, and errors exclude credentials, tokens and provider response bodies. Authentication happens only after verified TLS and advertised XOAUTH2 support. An OAuth failure never downgrades to a password or retries an email send.

Local offline grant setup

Use the executable scripts/google_grant.py flow in Connect Your Assistant. The agent prepares the permitted project/client and runs the helper on the approved computer; the owner enters credentials securely and completes Google’s consent. Installing Angelos does not create a grant or authorize project changes.

The helper uses a confidential Web application with the exact registered loopback redirect http://127.0.0.1:8401/callback, S256 PKCE, single-use state, offline access, and only https://mail.google.com/. Google permits HTTP localhost IP redirects for this flow. It exchanges the authorization code directly with Google’s fixed token endpoint, then checks the intended primary address through Gmail users/me/profile. The same Cloud project must have the Gmail API enabled for this identity check; API-disabled or administrator-denied responses fail setup with guidance. Redirect validation, Gmail API setup

The output is a new owner-only file outside Git, containing the verified mailbox and GOOGLE_* settings. Do not source it, print it, attach it, or copy the callback URL into chat. Transfer decoded values through the approved secure deployment route. Missing refresh tokens, a different mailbox, or missing/extra granted scopes stop the helper; no partial configuration is saved. No owner needs to copy an authorization code or operate OAuth Playground for this path.

This profile check does not change the runtime transport: mail still uses IMAP/SMTP, with the same Gmail-specific safeguards below. The callback runs only on the owner’s computer while the helper is active; no public Google callback endpoint is added to Angelos. Consent restrictions and token expiry remain Google’s decisions.

Workspace and consent restrictions

Workspace administrators can disable IMAP for users or organizational units, restrict approved OAuth client IDs, and block applications or sensitive data access. Internal applications may still need administrator approval. Ask the administrator to review the required access; do not weaken organization policy to make a connection work. IMAP policy, app controls

An Internal OAuth audience requires an organization-owned project and organization members. Consumer Gmail or users from other organizations need an External audience. External Testing is limited to listed test users, and mail authorizations/refresh tokens expire after seven days. Publishing an app and completing verification are separate steps. Google audience rules

Public distribution caveat

The full-mail scope is restricted. Public applications generally face verification and, when restricted data is handled server-side, security-assessment requirements unless a documented exception applies. Personal use and genuine internal use have exceptions; they do not waive consent or Workspace policy. Restricted-scope verification

Google’s current verification FAQ says IMAP/SMTP applications must have a genuine need for permanent deletion bypassing Trash to justify the full-mail scope; otherwise it directs developers to narrower Gmail API scopes. Angelos deliberately disables Gmail permanent deletion in this milestone. Therefore this implementation does not promise eligibility for a shared public Google OAuth application’s verification. Open-sourcing code is separate from operating such an application. A Gmail API adapter with narrower scopes is a possible later architecture, not an implemented feature. Destructive behavior will not be added merely to satisfy a verification criterion. Google verification FAQ

Explicit app-password alternative

Where the account and administrator permit it, select MAIL_AUTH_MODE=app_password with MAIL_PROVIDER=gmail and put an eligible Google app password in MAIL_PASSWORD. Clear the Google OAuth credential variables for this mode. Ordinary Google account passwords are not a supported alternative.

App passwords require 2-Step Verification and may be unavailable with organizational restrictions, security-key-only verification, or Advanced Protection. Account password changes revoke them. Eligibility must be checked by the owner/admin; Angelos neither creates app passwords nor changes security settings. Google app-password conditions, Workspace OAuth transition

Gmail mailbox behavior

• Gmail labels appear as IMAP folders. One message can have multiple folder/UID references. Existing folder/UIDVALIDITY/UID identity remains authoritative for actions; Gmail global message/thread IDs are not substituted.
• Special folders are discovered from actual LIST attributes, including when the server does not advertise SPECIAL-USE. Localized names are supported; ambiguous roles fail safely. All Mail is an aggregate and is not guessed as an Archive destination.
• Native MOVE support is checked at runtime. There is no COPY/Deleted/global-EXPUNGE emulation when it is absent.
• mail_delete_permanently is blocked for Gmail before any Deleted/EXPUNGE mutation. Gmail’s auto-expunge and last-label behavior depend on account settings; disappearance of one label UID does not prove permanent deletion.
• Gmail SMTP saves Sent automatically. Use append_sent: false. A true value is rejected before claim/SMTP, so the client can correct it without consuming the prepared ID. Backend Sent APPEND is also guarded.
• Gmail-specific X-GM-RAW, labels, global IDs, and thread APIs are not exposed as new tool inputs. The existing query remains plain IMAP text search, and generic keyword flags are not a Gmail label API.

Google IMAP extensions, Gmail client behavior, Gmail expunge settings

Reauthorization and testing

Grants can stop working after revocation, inactivity, password changes affecting Gmail scopes, token limits, time-limited access, or administrator changes. The owner must reauthorize or correct configuration through an approved flow. Never treat an authentication problem as permission to resend an unknown SMTP outcome. Google token lifecycle

Automated verification uses synthetic TLS IMAP/SMTP and token-endpoint fixtures: it covers refresh/cache/failure/redaction, XOAUTH2 exchanges, scope/gate separation, discovered roles, deletion rejection, Sent-copy prevention, and the existing durable send rules. No real Gmail grant, mailbox operation or delivery is established by those tests. Interactive consent UI, service-account domain-wide delegation, Gmail API transport, and account administration are outside this milestone.

Google setup and policy sources were checked on 2026-10-06. Live eligibility and administrator policy still need owner verification.