EXPLAINER

Gmail API Scopes and Verification

standardfreshness: volatilekey claims checked 2026-10-09

Gmail API scopes fall into non-sensitive, sensitive and restricted classes. Restricted scopes (including gmail.readonly) require OAuth app verification, a security assessment if you store the data on servers, and Google's Limited Use rules, which bar using that data to train generalised AI models.

Short answer: Before an AI agent reads mail, choose the narrowest Gmail scope: gmail.labels is non-sensitive, gmail.send is sensitive, and gmail.readonly, gmail.modify, gmail.compose, gmail.metadata and mail.google.com are all restricted — they need app verification and, when you store the data on your servers, a security assessment. Google's policy also forbids using this data to train or improve AI/ML models beyond that user's own personalised feature.

What is it?

"Readonly" sounds harmless, but for Gmail Google treats reading mail as one of its most sensitive permissions. If your app is for other people, you must pass Google's verification review, and if you keep their email data on a server you may need an independent security assessment. Google's rules also limit what you can do with the data: you can show it to the user inside your feature, but you cannot use it to train a general AI model or sell it. That matters a lot when the product is an AI agent.

Also known as: Gmail restricted scopes, gmail.readonly restricted, Gmail OAuth scopes, Google OAuth app verification, Google security assessment CASA, Limited Use policy Gmail, Google user data policy AI training, Gmail API permissions for agents.

Technical definition

Google's Gmail API scope page (checked on the date below) classifies scopes as: https://www.googleapis.com/auth/gmail.labels — non-sensitive; gmail.send — sensitive; and restricted: https://mail.google.com/, gmail.readonly, gmail.compose, gmail.insert, gmail.modify, gmail.metadata, gmail.settings.basic and gmail.settings.sharing (the last is described as restricted to administrative use by Google Workspace customers with a service account and domain-wide delegation). The page says restricted scopes "provide wide access to Google user data and require restricted scope OAuth App Verification" and that if you store restricted-scope data on servers (or transmit it) you must go through a security assessment. Google's Workspace user-data and developer policy (last updated 2026-09-03 on the date checked) sets Limited Use rules: limit use to providing or improving visible user-facing features; restrict transfers to consented feature delivery, security, legal compliance or an acquisition with consent; do not let humans read user data except with documented consent, for security, for legal compliance, or in aggregated and anonymised form; and prohibits transferring, selling or using user data to serve ads, to determine creditworthiness, or "to create, train, or improve a machine learning or artificial intelligence model beyond that specific user's personalized model for the appropriate use case or user-facing feature". Apps must include an attestation sentence about adhering to the Google User Data Policy including Limited Use. The older Google API Services User Data Policy page (last updated 2024-02-15) contains the human-reading and transfer limits but the AI/ML sentence was not found on it at check time, so treat the Workspace policy page as the source for that rule.

Entity type: standard · Freshness class: volatile.

When should I use it?

Read before choosing scopes for any Gmail-connected agent or when drafting a privacy notice for one. Not legal advice; confirm with Google's current policy and your counsel.

Implementation patterns

  • Map each tool to one scope: labelling → gmail.labels; sending → gmail.send; reading → a restricted scope (plan for verification).
  • Keep restricted-scope data off your servers where you can (client-side or per-request processing) to reduce assessment burden — confirm with Google's current requirements.
  • Never feed mailbox content into training or fine-tuning sets.
  • Document data flows and retention in the privacy policy and in the verification submission.

Technologies and frameworks

Commonly associated: Gmail API, Google OAuth 2.0, restricted-scope verification, Limited Use policy. Names are examples of what exists, not recommendations, and projects change quickly.

Practical guide

  1. List the exact actions the agent needs.
  2. Select the narrowest scope per action and check its class on the scopes page.
  3. Decide whether you will store mail data server-side; if so plan for the security assessment.
  4. Add the Limited Use attestation and a plain-language data-use notice.
  5. Exclude mail content from training, tuning and shared evaluation sets.
  6. Re-check Google's pages before launch — classes and policies change.

Common failure modes

  • Assuming "readonly" is a low-friction scope.
  • Shipping a prototype on a restricted scope to external users without verification.
  • Logging message bodies into an observability or evaluation dataset that is later used to tune a model.
  • Letting engineers browse user mail for debugging without the documented consent the policy requires.
  • Using the full-access scope mail.google.com when a narrower one exists.

Troubleshooting

  • Verification is rejected — Reduce requested scopes to what visible features need and explain each in the submission.
  • Need to debug with real messages — Use synthetic or consented test accounts; do not read user mail without documented consent.
  • Want to improve summaries using users' mail — Do not train a generalised model on it; per-user personalisation inside the feature is the allowed carve-out under the policy wording.

Contrasted with

Questions this page answers

  • Which Gmail scope should my AI agent use?
  • Is gmail.readonly a restricted scope?
  • Do I need a security assessment for a Gmail AI app?
  • Can I use Gmail data to train an AI model?
  • What is the Google Limited Use policy?

Typical goals: pick the minimum Gmail scope for an agent; understand the verification burden before building a Gmail agent; check whether email data can be used to improve a model.

Sources and verification

Status: key claims checked on 2026-10-09 against the primary sources listed below; everything else is not independently verified. The claims under "Checked against primary sources" were compared with the linked pages on that date. Pages change, so re-check anything time-sensitive before relying on it.

Checked against primary sources (2026-10-09):

  • Scope classes: gmail.labels non-sensitive; gmail.send sensitive; mail.google.com, gmail.readonly, gmail.compose, gmail.insert, gmail.modify, gmail.metadata, gmail.settings.basic and gmail.settings.sharing restricted. Add-on scopes (gmail.addons.current.*) also appear on the page and were not classified here.
  • Restricted scopes require restricted scope OAuth app verification; storing restricted-scope data on servers (or transmitting it) requires a security assessment.
  • Workspace policy Limited Use text: transfer limits, human-reading limits and the prohibition on using user data to create, train or improve an ML/AI model beyond that user's personalised model for the feature.
  • The Workspace policy page shows "Last updated 2026-09-03 UTC"; the older API Services policy page shows 2024-02-15 and did not contain the AI/ML sentence in the extracted text.

Primary sources consulted:

Not independently verified:

  • Fees, timelines and exact thresholds for verification and the security assessment.
  • Rules for unverified or internal-only apps (user caps, test-mode behaviour).
  • How the policy applies to consumer versus Workspace accounts and to enterprise admins who install an app for their own domain.
  • Whether the older API Services page omits the AI/ML sentence or the text extraction missed it.
  • Anything about legal obligations such as GDPR; this entry covers Google's platform rules only.

Freshness class: volatile — Products, versions, protocols, benchmarks, leaderboards, regulations and dates. Verify against the primary source before relying on specifics; re-review every 3 months.

Time-sensitive claims to verify before relying on them:

  • Which scopes are in each class.
  • Verification and security-assessment requirements, thresholds and fees.
  • Limited Use wording, including the AI/ML restriction (the Workspace page was last updated 2026-09-03).
  • Differences between consumer Gmail and Workspace-managed accounts.

Further reading and canonical sources (not all checked):

  • Choose Gmail API scopes (Google for Developers) — developers.google.com/workspace/gmail/api/auth/scopes
  • Google Workspace user data and developer policy — developers.google.com/workspace/workspace-api-user-data-developer-policy
  • Google API Services User Data Policy — developers.google.com/terms/api-services-user-data-policy