Summary
📝 Note
📚 Pilotflow Series: Building a Gmail Addon
- The $50,000 Lie That Almost Killed My Gmail Addon — June 8
- Gmail OAuth Scope Tiers Decoded ← you are here
- Pre-Development Codebase Analysis — June 22
- 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:
- During development: run the addon against test accounts on the approved list.
- Before launch: finish OAuth verification for the sensitive scopes actually in use.
- 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.