Image showing Gmail OAuth Scope Tiers: What Every Workspace Addon Developer Must Know

Gmail OAuth Scope Tiers: What Every Workspace Addon Developer Must Know

affiliate best offer

📝 Note

📚 Pilotflow Series: Building a Gmail Addon

  1. The $50,000 Lie That Almost Killed My Gmail Addon — June 8
  2. Gmail OAuth Scope Tiers Decoded ← you are here
  3. Pre-Development Codebase Analysis — June 22
  4. Legal Documents for Gmail Addons — June 29

TL;DR: Google sorts Gmail OAuth scopes into three tiers: non-sensitive, sensitive and restricted. The tier sets your verification path and the warning users see at install. Scopes that touch only the message the user has open are non-sensitive or sensitive. Scopes that touch the whole mailbox are restricted and bring a security assessment.

Two words in a Gmail scope name, “current message”, decide whether your OAuth review is plain verification or verification plus a third-party security assessment. Pick the wrong scope and you have signed up for the wrong path without knowing it.

I covered the certification cost myth in the last post. This post covers what decides whether that cost applies to you at all: Google’s three-tier scope classification, laid out in one place. The classification below comes from Google’s own scope page (Choose Gmail API scopes, last updated 2026-09-10, checked 2026-11-06). Assessment pricing depends on the lab and the scope of your app, so get quotes before you plan around any number.

Three Tiers, Three Different Review Paths

Your addon’s OAuth scopes don’t just gate what data you can touch. They decide which review Google puts you through. Google’s labels:

Non-sensitive scopes
  → Basic OAuth app verification
  → The narrowest access; Google recommends these for most use cases

Sensitive scopes
  → Additional OAuth app verification
  → Access to specific user data the user authorizes

Restricted scopes
  → Restricted-scope OAuth verification
  → A security assessment if you store (or transmit) restricted data on servers

An unverified app shows users a “Google hasn’t verified this app” screen. Google says that if you see it while testing, you must submit a verification request to remove it. Nobody has measured what that screen costs your install funnel yet, so assume it is not zero.

The Gmail Scope Table

Here’s the classification for the scopes most addon developers actually hit:

Scope Google’s label Access Review path
gmail.addons.current.message.action Non-sensitive Message the user has open, when they interact with the add-on Basic verification
gmail.addons.current.message.readonly Sensitive Message the user has open, while the add-on runs OAuth verification, no security assessment
gmail.addons.current.message.metadata Sensitive Metadata of the open message OAuth verification, no security assessment
gmail.send Sensitive Send email on the user’s behalf OAuth verification, no security assessment
gmail.readonly Restricted Read mail and settings Restricted verification, plus a security assessment if you store the data on servers
gmail.modify Restricted Read, compose and send, without permanent delete Same as above
https://mail.google.com/ Restricted Full access including permanent delete Same as above

Source: Choose Gmail API scopes, last updated 2026-09-10, checked 2026-11-06. Check it again before you decide: Google changes these tables.

Scopes that touch what the user is currently looking at land in non-sensitive or sensitive (gmail.send is sensitive too). Scopes that touch the entire mailbox in the background land in restricted. That split isn’t arbitrary: an addon reading the email a user just opened is under supervision. They opened it, they see the sidebar running, they can close both. An addon with standing inbox access can exfiltrate six months of email history while the user is in a meeting, and nothing about the UI would tell them.

A Scope Decision Example

A typical add-on loop is: open an email thread, see insights in the sidebar, decide what to do. That’s gmail.addons.current.message.readonly, exactly, with nothing left over.

That loop is not background batch processing: scanning six months of history while the user does something else. It is tempting to ask for that access anyway, because more access feels like more optionality, and “more optionality” is exactly the trap.

📝 Note — The “just in case” trap

Requesting broad scopes “just in case” is the single most common mistake in scope design, and it has a cost. Every unused permission is a trust liability sitting on your consent screen, not a safety net in your back pocket. Ask what the user is doing at the moment your addon runs, not what you might want to do with their data six months from now.

The Testing Status Strategy

While your OAuth consent screen is in “Testing” status, only the test users you list can authorize the app (Google’s limit is 100), and users see the unverified-app warning. That makes it useful for development and for validating a feature with real email data, and not for a public launch.

A sequence that follows from the tiers:

  1. During development: run the addon against test accounts on the approved list.
  2. Before launch: finish OAuth verification for the sensitive scopes actually in use.
  3. After launch: ship only the features that need sensitive scopes. Collect demand (a waitlist, for example) for any feature that needs a restricted scope before you commission a security assessment.

If nobody asks for the restricted feature, nobody pays for the assessment. Validate demand first, commit money second.

What Happens If You Get It Wrong

Request a sensitive or restricted scope without the matching verification and your users see the unverified-app screen, with a back button sitting right there. Some proceed anyway. Some don’t. For a B2B addon aimed at enterprises, Workspace admins can also restrict which third-party apps their users may install, which is a worse outcome than a slow launch.

If you request a restricted scope and store that data on servers, Google expects a completed security assessment. Plan for it before you commit to the feature, not after.

ℹ️ Info: plan for the review time

Verification and assessment timelines vary with Google’s queue and with the assessor you pick (an authorized third-party lab). Put them on the calendar before you write code, not after.

The Question That Actually Matters

Every scope decision comes down to one question, asked before you touch googleapis.com: what is the user doing, right now, when your addon fires? If the answer is “reading one email,” you don’t need the entire mailbox, and asking for it anyway moves you to a heavier review path for no product benefit. Shipping the narrower scope and answering “why don’t you support X” emails is cheaper than a security assessment you did not need.


Frequently Asked Questions

What are the three Gmail OAuth scope tiers?

Non-sensitive scopes need basic OAuth verification. Sensitive scopes need additional OAuth verification. Restricted scopes need restricted-scope verification, plus a security assessment if you store the data on servers.

Which Gmail scopes are restricted?

gmail.readonly, gmail.modify and https://mail.google.com/ are restricted because they give wide access to the mailbox. Scopes limited to the currently open message, such as gmail.addons.current.message.readonly, are sensitive, and gmail.send is sensitive too.

Can I test a restricted scope before paying for certification?

Yes, for development and validation. While the consent screen is in Testing status, up to 100 listed test users can authorize the app. It is not a way to launch publicly.

What happens if I request a restricted scope without a security assessment?

If you store restricted-scope data on servers, Google requires a security assessment. Without the verification steps, users see an unverified-app screen. Check Google’s current requirements before you commit.

Full Bright

Full Bright

A professional and sympathic business man.

Contact

Contact Us

Not sure which of these you need? Book the free 20-minute audit — we look at one week of your work and tell you what is worth automating, what is not, and what it would cost. Book it here.

One audit call a week, Thursdays or Fridays — book early if a specific day matters to you.

Address

10 rue François 1er,
75008 Paris

When we work

Monday - Friday
9:00AM - 05:00PM