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
Two words separate a free, four-week OAuth review from a certification that can run past $75,000: “current message.” Miss that distinction in a Gmail scope name and you’ve signed up for the wrong tier without knowing it.
I covered the certification cost myth in the last post. The $50K figure that circulates is the ceiling, not the standard price. This post is about the piece that decides which price applies to you at all: Google’s three-tier scope classification, which most addon documentation never lays out in one place. I pieced it together from error messages during OAuth verification. That is a worse way to learn it than reading it here.
Three Tiers, Three Different Conversations
Your addon’s OAuth scopes don’t just gate what data you can touch. They script the exact conversation Google has with your user at install time.
Tier 1: Public scopes
→ Standard OAuth consent screen
→ No additional verification required
→ Blue shield icon in consent dialog
Tier 2: Sensitive scopes
→ OAuth verification required (free, 4–6 weeks)
→ Yellow/orange warning in consent dialog
→ Users must explicitly accept extended access
Tier 3: Restricted scopes
→ CASA Tier 2 certification required ($540–$75,000+)
→ Red warning in consent dialog
→ Enterprise admins can block installation
A red warning at install time is a different first impression than a blue shield, full stop. That’s not a compliance detail. It’s a conversion number you haven’t measured yet.
The Gmail Scope Table
Here’s the classification for the scopes most addon developers actually hit:
| Scope | Tier | Access | Certification |
|---|---|---|---|
gmail.addons.current.message.readonly |
Sensitive | Currently open message only | OAuth verification (free) |
gmail.addons.current.message.action |
Sensitive | Action on current message | OAuth verification (free) |
calendar.addons.current.event.read |
Public | Current calendar event | None |
gmail.readonly |
Restricted | Entire inbox (read) | CASA + OAuth |
gmail.modify |
Restricted | Entire inbox (read + modify) | CASA + OAuth |
gmail.send |
Restricted | Send as user | CASA + OAuth |
Scopes that touch what the user is currently looking at land in public or sensitive. 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.
Pilotflow’s Scope Decision
Pilotflow’s core 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.
What it isn’t is background batch processing: scanning six months of history while the user does something else. I wanted that at one point. Not because the product needed it, but because more access felt 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’s not free. 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
Restricted-scope APIs can behave differently pre-certification than post-certification, since your app isn’t certified yet. Google’s answer is a “Testing” status: up to 100 approved test accounts, full functionality, zero certification required.
That’s the sequence I ran for Pilotflow:
- During development: run the addon against a test Gmail account on the approved list.
- Before MVP launch: finish OAuth verification for the sensitive scopes actually in use.
- After launch: watch whether real users ever hit a restricted-scope feature before paying for CASA.
If nobody asks for the restricted feature, nobody pays for the assessment. That’s the whole strategy: validate with real email data first, commit money second.
What Happens If You Get It Wrong
I’ve watched both failure modes happen.
Request a restricted scope without certification and the Workspace Marketplace review doesn’t flag it. It rejects the submission outright. Google’s reviewers check scope classification against certification status as a hard gate, not a warning.
Request a sensitive scope without OAuth verification and users hit “This app hasn’t been verified by Google,” with a back button sitting right there. Some proceed anyway. A lot don’t: public abandonment estimates on unverified consent screens run 30–50%. For a B2B addon aimed at enterprise, unverified status can also trigger an admin-level block across the whole org, which is a worse outcome than a slow launch.
ℹ️ Info — The verification timeline to plan for
OAuth verification: 4–6 weeks. CASA assessment: 4–12 weeks depending on the TAP and assessment type. Put that 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 just moves you from a blue shield to a red one for no product benefit. I’d rather ship the narrower scope and answer “why don’t you support X” emails than ship the broad one and answer a Google reviewer’s rejection.
The next post covers pre-development codebase analysis: what I found analyzing the existing codebase before writing a line of new code, including a concurrency bug that would have caused silent data loss.
