OAuth app readiness guide · Email

Getting your Gmail app ready for real users

Tested in a real setup attemptChecked 2026-10-28gmail.com

Verdict. The scope you pick decides the project. Sending mail needs a short verification. Reading mail means restricted-scope review plus a paid security assessment renewed every year. Until verified, your app is capped at 100 users for its lifetime and test tokens die after 7 days.

At a glance

The answer in one screen

Ease of creation

Moderate

About 10 minutes to a Testing-mode app in our test.

Ease of approval

Very hard (read)

Read access needs verification plus a CASA security assessment. Send-only is moderate.

Your hands-on time

1 to 3 days

Domain verification, privacy policy, demo video, scope justifications. Plus assessor work for read access.

Waiting on the provider

Days to 6 weeks

Brand check 2 to 3 business days; sensitive scopes under a week; restricted scopes plus CASA several weeks.

Do you need your own app yet?

Start on Composio's managed Gmail app.

It skips verification for you, but users see Composio on Google's consent screen, scopes are fixed (full mailbox in Composio's own test) and quota is shared. Move to your own app when branding or narrow scopes matter.

Watch out: decisions you can't undo

The 100-user cap counts for the app's lifetime. Use a separate Google Cloud project for development and testing so you do not burn your production project's 100 users.
"Internal" is only for Google Workspace organizations. Solo developers and startups without Workspace should plan for verification from day one.
Uploading a logo triggers verification. Skip the logo until you are ready to submit.
Adding a restricted scope later means a new assessment. Pick your restricted scopes once, before the assessment.

Agent an agent can do it You needs you Waiting on the provider

Prerequisites

What to have ready

To create and connect

A Google account and a new Google Cloud project (separate one for testing)
User support email: your account or a Google Group you manage (a shared inbox must be a Group)
Agreement to the Google API Services User Data Policy

For approval (can take days)

Public homepage and privacy policy on the same domain, linked from the consent screen
Domain ownership verified in Google Search Console
Unlisted YouTube demo video showing the consent screen, client ID and each scope in use
Scope justifications naming the feature and why narrower scopes won't work
Restricted scopes: a CASA assessment through an authorized assessor (reported cost about $540 to $3,000+)

App types

Which one is right for an agent product?

Testing (External)

The default after setup.

Who can install: Listed test users only, max 100 for the app's lifetime
Review: None
Use it for: Development; never for customers

Recommended for agents

Production (External), verified

After brand and data access verification.

Who can install: Any Google account
Review: Yes. Restricted scopes add CASA
Use it for: Agent products with customers

Internal

Only for projects in a Google Workspace organization.

Who can install: Users in your own Workspace
Review: None
Use it for: Internal tools at your own company

Composio's managed app is a valid launch pathMany teams launch on Composio's verified Gmail app and move to their own once the product is proven. You trade branding, scope control and dedicated quota for skipping the review. Secondary source

Creation steps

Who does what, and how long it takes

YouSign in and create a project
1 min
console.cloud.google.com. The console may stay on another project until you switch.
AgentRun the Google Auth Platform setup
4 min
App name, support email, audience (External), contact email.
YouAgree to the User Data Policy and create
10 sec
Configuration is created in Testing status.
AgentAdd scopes under Data Access
3 min
Gmail scopes only appear once the Gmail API is enabled; otherwise paste them in "Manually add scopes".
AgentCreate an OAuth client
2 min
Web application, with the Composio callback as the redirect URI.
YouVerify your domain
30 min to 1 day
In Google Search Console, with DNS or site access. An agent cannot do this for you.
YouComplete Branding and record the video
2 to 4 hours
Homepage, privacy policy, terms, authorized domains, demo video.
WaitingBrand and data access verification
Days
Brand check 2 to 3 business days. Sensitive scopes typically under a week.
YouCASA assessment (restricted scopes only)
5 to 20 days
Scan, fix findings, answer the questionnaire, respond daily.

In our test: about 10 minutes to a Testing-mode app with Gmail scopes and three approvals. Production needs the human-only steps above.

Scopes

What each permission costs you

Google classifies every scope as non-sensitive, sensitive or restricted. The console sorted our scopes into these groups for us.

Agent use case	Scopes	What it costs you
Manage labels only	`gmail.labels`	Non-sensitive: brand check only
Send email on the user's behalf	`gmail.send`	Sensitive: verification, no CASA
Read messages and settings	`gmail.readonly`	Restricted: verification + CASA yearly
Read headers only	`gmail.metadata`	Restricted too, despite sounding light
Drafts, modify, labels on mail	`gmail.composegmail.modify`	Restricted
Full mailbox	`https://mail.google.com/`	Restricted; hardest to justify

Minimal set: "Send follow-ups" agentgmail.send

Avoids CASA entirely.

Minimal set: "Triage my inbox" agentgmail.readonlygmail.send

Restricted: budget for CASA and several weeks.

Changing scopes later

Adding a sensitive scope means re-verification.
Adding a restricted scope means re-verification and possibly a new security assessment.
Users can grant only some scopes (granular consent). Check granted scopes after every connection.

Approval and distribution

Review, cost and renewal

When you need it: Before any user outside your test list, and before your 100th user ever. Cost: Verification is free. CASA through an assessor: reported about $540 to $3,000+ per year. Renewal: Restricted scopes: CASA at least every 12 months. Google emails about 90 days before expiry.

Brand

2 to 3 business days

Publish within 7 days of a compliant result.

Sensitive

Under a week

Typical for send-only.

Restricted

Several weeks

Google says several weeks; prepared teams report 5 to 20 days.

CASA

5 to 20 days

With an authorized assessor, then a Letter of Assessment.

What you submit

Homepage, privacy policy, verified domain
Demo video
Scope justifications
CASA results for restricted scopes

Common rejection reasons

Requesting scopes you don't use
Video not showing each scope
Privacy policy missing Limited Use language
Unmonitored contact email

Replying to Google and your assessor quickly is the biggest lever on time.

Before approval: what works and what's capped

Build and test

Testing mode, listed test users.

Limit: 100 users for the app's lifetime; refresh tokens expire after 7 days; "unverified app" screen.

First customers

Composio's managed app, or your app once verified.

Limit: Your own unverified app is not usable for customers.

Scale

Verified app.

Limit: Restricted scopes: yearly CASA renewal.

The 7-day trapIn Testing, refresh tokens expire after 7 days. An agent that works in your demo will silently disconnect a week later. Secondary source

Data use and compliance

Rules that shape agent design

Limited Use. Google user data may only be used to provide or improve user-facing features.
No general model training on Workspace data. Disclose any AI use in the product and the privacy policy.
Security assessment is required when restricted-scope data can be reached from or through your servers.

Design impactIf your agent reads mail, budget for CASA, a yearly renewal and an AI-use disclosure. Official docs

Common blockers

Symptom, cause, fix

Symptom	Cause	Fix
"Google hasn't verified this app" screen	Testing mode or unverified production app	Complete verification, or use Composio's managed app
Users disconnected after a week	Testing-mode refresh tokens expire after 7 days	Move to production and verify
Gmail scopes missing in the picker	Gmail API not enabled	Enable the API or paste the scope URLs manually
Cannot pick Internal	No Google Workspace organization	Use External and plan for verification
Review stalls	Contact inbox not monitored	Use a monitored Google Group and add a second project editor

Sources

Where every claim comes from

Claim	Source
100-user cap counted over the app's lifetime	Tested in our setup
gmail.send sensitive; gmail.readonly restricted	Tested in our setup
gmail.metadata is restricted	Official docs
Internal disabled without Workspace	Tested in our setup
Logo upload triggers verification	Tested in our setup
Testing refresh tokens expire after 7 days	Secondary source
CASA cost range	Secondary source

All sources

Gmail API scopes developers.google.com
Google: Restricted scope verification developers.google.cn
Nango: Google security review nango.dev
Composio: Ship a Gmail integration composio.dev