Summary
[!note] 📚 Pilotflow Pre-Launch Series
- The $50,000 Gmail Add-on Myth
- Gmail OAuth Scopes Decoded ← you are here
- Pre-Development Codebase Review: Finding Bugs Before You Write Code — March 18
- Legal Documents for Gmail Add-ons in 15 Minutes — March 20
In the previous post, I covered the real cost of Google’s CASA certification — much lower than the $50K figure that circulates online. But knowing the cost only matters if you know which scopes trigger it.
This is where most Gmail add-on developers get surprised: by a one-word difference in scope names that completely changes the certification requirement.
The Three-Tier Classification System
Google classifies all OAuth scopes for Workspace Marketplace apps into three categories. Your launch path is determined entirely by which category your scopes fall into.
Tier 1: Public Scopes
Examples: userinfo.email, userinfo.profile
These scopes access basic account information. No special certification required — just the standard OAuth consent screen process.
Tier 2: Sensitive Scopes
Examples: gmail.labels, gmail.send, calendar.events
These scopes can modify user data or access potentially sensitive information, but they don’t grant access to the full content of your inbox or Drive. For Workspace Marketplace apps, they require OAuth verification — a free process that takes 4–6 weeks for Google to review.
Tier 3: Restricted Scopes
Examples: gmail.readonly (full inbox), gmail.modify, drive.readonly (all files)
These scopes access the full contents of a user’s inbox or Drive. They require CASA Tier 2 certification in addition to OAuth verification.
The Trap: gmail.readonly vs gmail.addons.current.message.readonly
Here’s the detail that catches most developers:
| Scope | Access | CASA Required? |
|---|---|---|
gmail.readonly |
Read entire inbox (all messages, all threads) | Yes — Restricted |
gmail.addons.current.message.readonly |
Read only the currently open message in the add-on sidebar | No — Sensitive |
Same word (“readonly”). Completely different certification tier.
If your add-on only needs to read the email a user has currently open — to display context, extract metadata, or take an action based on it — you do not need gmail.readonly. The narrower contextual scope does the same job without triggering CASA.
This one distinction can save you an annual certification cost and a multi-week assessment process.
Mapping Pilotflow’s 7 Scopes
Pilotflow (the Gmail inbox manager) uses seven scopes. Here’s how each one maps to the certification tiers:
| Scope | Category | CASA? | Why it’s needed |
|---|---|---|---|
gmail.labels |
Sensitive | No | Create and apply labels (core feature) |
gmail.send |
Sensitive | No | Send processed emails |
gmail.modify |
Restricted | Yes | Move emails, mark read/unread |
drive.file |
Sensitive | No | Read/write files the user explicitly opens |
spreadsheets |
Sensitive | No | Write rules to a Google Sheet |
script.projects |
Sensitive | No | Access Apps Script project |
script.scriptapp |
Sensitive | No | Execute the script |
Of the seven scopes, only gmail.modify is restricted. The other six are sensitive.
The “Testing Status” Strategy
Here’s the key insight for shipping a restricted-scope add-on before investing in CASA certification:
Google allows Workspace add-ons to operate in Testing Status with up to 100 users — without Marketplace approval or CASA certification. The add-on is private, shared by invitation only, but it’s fully functional.
This creates a clean validation pathway:
- Build the full product with all required scopes
- Publish to Testing Status (no certification needed)
- Test with up to 100 real users
- Generate revenue signals
- Decide whether to invest in CASA certification based on actual usage data
For Pilotflow, the decision was: use all 7 scopes, ship to Testing Status, validate with real users. The CASA investment decision gets made when there’s revenue to support it — not speculatively, before a single user has tried the product.
This is the lean product launch applied to platform certification. Don’t invest in compliance before you know the product has market fit.
Key Takeaways
- Gmail OAuth scopes fall into three tiers: Public (no cert), Sensitive (OAuth verification, free), and Restricted (CASA Tier 2, $540–$1,800/yr).
- The
gmail.readonlyvsgmail.addons.current.message.readonlydistinction can eliminate CASA requirements entirely if your add-on only needs contextual message access. - Testing Status (up to 100 users, no CASA) is the right first step for restricted-scope add-ons. Validate first, certify when the revenue justifies it.
What’s Next
Choosing the right scopes is a planning decision. But before I wrote any new code for Pilotflow, I did something that most developers skip entirely: a systematic review of the existing codebase. It found a bug I didn’t know existed.
→ Next: Pre-Development Codebase Review
← Previous: The $50,000 Gmail Add-on Myth
— Kékéli
