LinkedIn
Instagram
WhatsApp
Telegram
Google Calendar
Join Slack CommunityGmail API Scopes Explained: Choose the Right Permissions for Your App
Every Gmail API scope documented: from gmail.readonly to mail.google.com. Understand the 3 sensitivity levels, pick the minimum scope your app actually needs, and ship your OAuth flow faster.
// Request Gmail API scopes in OAuth flow
const SCOPES = [
'https://www.googleapis.com/auth/gmail.readonly',
'https://www.googleapis.com/auth/gmail.send',
'https://www.googleapis.com/auth/gmail.labels',
];
const authUrl = oauth2Client.generateAuthUrl({
access_type: 'offline',
scope: SCOPES,
prompt: 'consent',
});What Are Gmail API Scopes?
Before writing a single line of OAuth code, you need to understand what Gmail API scopes are and why choosing the wrong one can block your app from going to production. This section gives you the foundational knowledge in under two minutes.
Gmail API scopes are OAuth 2.0 permission strings that define exactly which Gmail resources your application can access on behalf of a user. When a user authorizes your app, Google presents a consent screen listing the Gmail API scopes your app requested. The user grants or denies access based on those scopes. Once granted, your access token is limited to exactly the actions those scopes permit - nothing more.
Gmail API scopes create a hard boundary around what your token can do. Even if your server is compromised, an attacker with a gmail.readonly token cannot send or delete emails. Scopes are enforced server-side by Google.
Restricted Gmail API scopes require your app to pass Google's security assessment before you can use them in production with more than 100 test users. The wrong scope choice can add weeks or months to your launch timeline.
Requesting more Gmail API permissions than your app needs triggers a "This app wants broad access to your Google Account" warning. Minimal Gmail API scopes produce a simpler consent screen, increasing conversion and user trust.
Skip scope management entirely. Unipile handles Gmail OAuth and scopes internally - your team focuses on product logic, not permission strings.
Build it with UnipileThe 3 Sensitivity Levels Explained
Google classifies all Gmail API scopes into 3 sensitivity levels. Each level determines the verification requirements before your app can go live. Understanding this classification is the most important decision you make when planning your Gmail integration.
The lowest risk tier. These scopes access limited, non-personal Gmail data. Google does not require a formal security assessment to use them in production.
Medium risk tier. These scopes access Gmail message data that could expose personal information. Additional verification is required before production use.
Highest risk tier. These scopes grant broad or sensitive access to Gmail data. Google requires a formal security assessment by an approved third-party auditor.
| Criteria | Non-sensitive | Sensitive | Restricted |
|---|---|---|---|
| Accesses message body | No | Sometimes | Yes |
| Security assessment required | No | No | Yes |
| App review required | Yes | Yes | Yes |
| Annual re-certification | No | No | Yes |
| Consent screen warning level | Standard | Standard + disclosure | Broad access warning |
| Typical cost to verify | Free | Free | ~$500/yr (assessor) |
Full Gmail API Scope Reference
The complete list of Gmail API scopes, grouped by sensitivity level. Use this table as your single reference when choosing gmail api permissions for your application. Scopes marked "2026" reflect the latest additions to Google's scope list.
| Scope URI | Access Level | What It Accesses | When to Use |
|---|---|---|---|
| gmail.addons.current.action.compose | Non-sensitive | Allows add-ons to compose and send email during a compose action | Gmail add-ons that draft or send email on behalf of user within the compose window |
| gmail.addons.current.message.action | Non-sensitive | Allows add-ons to view the current email during a message action | Gmail add-ons that react to a message action (archiving, labeling) in the message context |
| gmail.labels 2026 | Non-sensitive | See and edit labels (create, rename, delete), but not message content | Apps that organize email with labels without needing to read message bodies |
| Scope URI | Access Level | What It Accesses | When to Use |
|---|---|---|---|
| gmail.addons.current.message.metadata | Sensitive | Email headers and metadata (From, To, Subject, Date) in add-on context - not message body | Add-ons that display contextual information based on sender or subject without reading body |
| gmail.addons.current.message.readonly | Sensitive | Full read access to the current email including body and attachments, in add-on context | Add-ons that analyze or extract data from the currently open message |
| gmail.send | Sensitive | Send email on behalf of the authenticated user - no read or modify access | Apps that only send transactional or outreach emails and do not need to read inbox |
| Scope URI | Access Level | What It Accesses | When to Use |
|---|---|---|---|
| mail.google.com/ | Restricted | Full mailbox access: read, compose, send, and permanently delete emails and settings | Only when you need every Gmail capability in one scope - typically legacy integrations |
| gmail.readonly | Restricted | Read-only access to all messages, threads, labels, and settings - cannot send or modify | Analytics, archiving, search, or email intelligence tools that only read inbox data |
| gmail.compose | Restricted | Create and manage drafts, and send those drafts - no access to existing emails | Draft management tools, email composers, or apps that queue emails before sending |
| gmail.insert 2026 | Restricted | Insert messages into Gmail mailbox only - cannot read or send existing emails | Migration tools or systems that import emails into Gmail from external sources |
| gmail.modify | Restricted | Read, compose, send, and manage emails and labels - cannot permanently delete | Full-featured email clients, CRM sync tools, helpdesk integrations needing read+send+label |
| gmail.metadata | Restricted | Headers and labels only - no access to email body or attachments | Apps that categorize or route emails based on metadata without reading private content |
| gmail.settings.basic | Restricted | Manage basic Gmail settings: filters, forwarding rules, POP/IMAP settings | Email productivity tools that configure Gmail routing or filtering on behalf of users |
| gmail.settings.sharing | Restricted | Sensitive settings management: send-as aliases, delegates, vacation responders (domain admin only) | Workspace admin tools only - requires domain administrator privileges to enable |
Don't manage these gmail api scopes manually. Unipile's Gmail integration handles OAuth scope requests, token refresh, and re-authorization flows automatically across your users' linked accounts.
Build your Gmail appWhich Gmail API Scope Do You Need?
The single most important principle in Gmail API scope selection is the principle of minimum access: request only the gmail api permissions your app actually needs. This table maps common use cases to the minimum recommended scope, helping you avoid unnecessary verification overhead and protect user trust.
| Use Case | Minimum Scope | Verification Level | Notes |
|---|---|---|---|
| Send emails only (no inbox read) | gmail.send | Sensitive | Ideal for transactional or outreach tools. No access to existing messages. |
| Read inbox for analytics or search | gmail.readonly | Restricted | Full read access to all messages and settings. Requires annual security assessment. |
| Full email client (read + send + label) | gmail.modify | Restricted | Preferred over mail.google.com/ as it excludes permanent delete. Covers most CRM and helpdesk use cases. |
| Archive or backup emails permanently | mail.google.com/ | Restricted | Only use when you truly need delete access. Triggers the broadest Google consent warning. |
| Organize labels only | gmail.labels | Non-sensitive | New in 2026. Minimal permissions for label management without reading messages. |
| Draft management (queue before send) | gmail.compose | Restricted | Access to drafts and send capability, but no read access to existing messages. |
| Metadata routing or categorization | gmail.metadata | Restricted | Headers and labels only - no body access. Good for routing engines that respect message privacy. |
| Email migration / import into Gmail | gmail.insert | Restricted | New in 2026. Insert-only access - better scoped alternative to mail.google.com/ for import tools. |
| Configure Gmail filters and forwarding | gmail.settings.basic | Restricted | Manage filters, labels, forwarding rules. No message body access. |
| Gmail add-on: display sender context | gmail.addons.current.message.metadata | Sensitive | Headers only in add-on context. Avoids full message read access. |
You can combine multiple gmail api scopes in a single OAuth request (e.g., gmail.send + gmail.labels), but each scope adds to the consent screen disclosure. Always audit your scope list before going to production. If you are building a full Gmail sync product, the OAuth Email API guide covers the complete flow including token management and scope re-authorization.
Restricted Scope Verification: What It Means for Your App
If your app needs any restricted Gmail API scope - including gmail.readonly, gmail.modify, or mail.google.com/ - you must complete Google's security assessment process before going live beyond 100 test users. Here is what that process looks like and how to minimize the overhead.
Create a project, enable the Gmail API, and configure the OAuth consent screen. Fill in all required fields: app name, support email, authorized domains, and privacy policy URL. This step is required for any Gmail API scope level.
In the OAuth consent screen, click "Prepare for Verification". Declare each restricted Gmail API scope and provide a justification explaining why your app needs it. Google's team reviews this before routing you to a security assessor.
Google routes restricted scope apps to an approved assessor (Leviathan Security, Coalfire, etc.). The assessment costs approximately $500/year. You must provide a demo, explain data handling practices, and pass a technical review of your OAuth implementation.
Restricted Gmail API scopes require yearly re-certification. If you miss the renewal window, Google can revoke your app's production access. Plan for this recurring cost and compliance cycle from day one of your Gmail integration architecture.
Choose gmail.send over gmail.modify when your app only sends emails and does not need to read the inbox. gmail.send is a sensitive (not restricted) scope and skips the security assessment entirely.
Use gmail.metadata instead of gmail.readonly if your app routes or categorizes emails without reading body content. You still need verification, but the scope is narrower and easier to justify to Google.
Use a platform that already holds Google verification. When you build on top of Unipile's Gmail integration, your app benefits from Unipile's pre-verified OAuth credentials, so you do not need to go through the restricted scope assessment yourself. This is the fastest path to production for most SaaS products.
Stay in the 100-user testing window during early development. You can test restricted Gmail API scopes with up to 100 Google accounts without completing the full verification. Add test accounts in the Google Cloud Console OAuth consent screen settings.
Skip the Google verification process entirely. Unipile's hosted Gmail OAuth is already verified for restricted gmail api scopes - your linked accounts connect immediately without additional assessment.
Start building todayHow to Request Gmail API Scopes in Your OAuth Flow
Once you know which gmail oauth scopes your app needs, you declare them when generating the authorization URL. Here are working code examples in both Node.js and Python showing exactly how to pass gmail api permissions into the OAuth consent screen.
// Node.js — Gmail API scopes in OAuth flow
// Uses google-auth-library (official Google client)
const { OAuth2Client } = require('google-auth-library');
const oauth2Client = new OAuth2Client(
process.env.GOOGLE_CLIENT_ID,
process.env.GOOGLE_CLIENT_SECRET,
process.env.REDIRECT_URI
);
// Define the gmail api scopes your app needs
// Principle: request minimum scope required
const SCOPES = [
'https://www.googleapis.com/auth/gmail.readonly', // restricted
'https://www.googleapis.com/auth/gmail.send', // sensitive
'https://www.googleapis.com/auth/gmail.labels', // non-sensitive
];
// Generate the OAuth authorization URL
const authUrl = oauth2Client.generateAuthUrl({
access_type: 'offline', // request refresh token
scope: SCOPES,
prompt: 'consent', // force consent to get refresh token
});
console.log('Redirect user to:', authUrl);
// After user authorizes, exchange code for tokens
async function getTokens(code) {
const { tokens } = await oauth2Client.getToken(code);
oauth2Client.setCredentials(tokens);
return tokens;
}# Python — Gmail API scopes in OAuth flow
# Uses google-auth-oauthlib (official Google library)
from google_auth_oauthlib.flow import InstalledAppFlow
from google.oauth2.credentials import Credentials
from google.auth.transport.requests import Request
import os
# Define gmail api scopes - request only what you need
SCOPES = [
'https://www.googleapis.com/auth/gmail.readonly', # restricted
'https://www.googleapis.com/auth/gmail.send', # sensitive
'https://www.googleapis.com/auth/gmail.labels', # non-sensitive
]
def get_gmail_credentials():
creds = None
# Load existing token if available
if os.path.exists('token.json'):
creds = Credentials.from_authorized_user_file(
'token.json', SCOPES
)
# Refresh or request new credentials
if not creds or not creds.valid:
if creds and creds.expired and creds.refresh_token:
creds.refresh(Request())
else:
# Trigger OAuth consent screen with declared scopes
flow = InstalledAppFlow.from_client_secrets_file(
'credentials.json', SCOPES
)
creds = flow.run_local_server(port=0)
# Persist token for future runs
with open('token.json', 'w') as token:
token.write(creds.to_json())
return credsImportant: The prompt: 'consent' (Node.js) or run_local_server call (Python) forces the Google consent screen to appear even if the user has previously authorized. This is required to reliably get a refresh_token. Without a refresh token, your access token expires after 1 hour and users must re-authorize. For a complete guide to handling token refresh and scope re-authorization, see the OAuth Email API guide and the Unipile Google OAuth docs.
Minimum Scope Principle and Compliance
The minimum scope principle is not just a Google recommendation - it directly affects your GDPR and SOC 2 compliance posture. Requesting excessive gmail api permissions creates unnecessary data exposure risks and complicates your data processing agreements with end users.
The minimum scope principle mirrors the security concept of least privilege. Your Gmail API integration should request the lowest-permission gmail api scope that enables the feature. If your CRM only sends follow-up emails, gmail.send is enough - gmail.modify is excessive and creates unnecessary risk.
Google surfaces your declared gmail api scopes directly on the consent screen. Broader scopes trigger more alarming language ("This app wants access to your entire Gmail inbox"). Minimal gmail oauth scopes produce simpler, less intimidating consent screens - typically improving authorization conversion rates by 15-30% in user-facing OAuth flows.
Your privacy policy and DPA (Data Processing Agreement) must accurately reflect which Gmail data your app accesses. If your app requests gmail.readonly but your privacy policy only mentions "sending emails," you have a GDPR documentation gap. Match your declared gmail api scopes to your published data practices.
Gmail API scope requirements evolve as features are added or removed. Conduct a scope audit at each major release: remove any gmail api permissions your current feature set no longer requires. Unused scopes in your OAuth declaration are a compliance liability - they represent data access you claim to need but don't use.
gmail.metadata instead of gmail.readonly when body access is not needed
Compliance-ready Gmail integration. Unipile's Gmail API implementation follows the minimum scope principle by default - your app only requests the gmail oauth scopes needed for the features you enable.
Build compliant Gmail appsGmail API Scopes with Unipile: Skip the Scope Complexity
Managing gmail api scopes manually means navigating Google's verification process, handling token refresh on scope changes, and updating your data processing documentation every time you add a feature. Unipile abstracts this entirely, your team focuses on product, not permission strings.
Gmail
Outlook
IMAP
Unipile holds Google's OAuth verification for restricted gmail api scopes. Your app benefits immediately without completing a separate security assessment. The annual re-certification is handled by Unipile's compliance team.
Unipile manages OAuth token refresh, scope validation, and re-authorization flows for each of your users' linked accounts. When Google updates scope requirements, Unipile adapts without breaking your integration.
The same Unipile API calls work for Gmail, Outlook, and IMAP. You write your email feature once and it works across all providers, no separate gmail api scope management per provider, no protocol-specific code branches.
For teams that need to use their own Google credentials, Unipile supports white-label OAuth configuration. Your users see your brand on the consent screen while Unipile handles the scope declaration and token lifecycle in the background.
Unipile's Gmail integration requests only the gmail api permissions required for the features you enable. Read, send, sync, each capability maps to the narrowest scope possible, keeping your compliance profile clean.
Receive new Gmail messages as they arrive via Unipile webhooks. No polling, no managing Gmail Pub/Sub subscriptions manually. Works with the same OAuth token your app already uses for other Gmail API operations.
Frequently Asked Questions about Gmail API Scopes
Common questions about gmail api scopes, gmail oauth scopes, and the verification process - answered concisely for developers building Gmail integrations.
gmail.readonly and gmail.modify are restricted gmail api scopes. gmail.readonly provides read-only access to all messages, threads, labels, and settings - your app cannot send or change anything. gmail.modify adds the ability to read, compose, send emails, and manage labels, but excludes permanent message deletion. If your app needs to read and send but not delete, gmail.modify is preferred over the broader mail.google.com/ scope. See our how to read user emails via a unified API.gmail.labels require only standard OAuth app review. Sensitive scopes like gmail.send require Google's OAuth verification process but no security assessment. Restricted scopes - including gmail.readonly, gmail.modify, gmail.compose, gmail.metadata, gmail.insert, and mail.google.com/ - require the full assessment process. More on this in our secure email API patterns for regulated industries.gmail.modify scope grants read, compose, send, and label management access to Gmail, but excludes the ability to permanently delete messages. It is the recommended restricted scope for full-featured email integrations such as CRM email sync, helpdesk tools, and email clients that need to both read and send messages. It is preferred over mail.google.com/ because it limits data exposure by excluding permanent delete functionality. Related: sending email on behalf of users.scope parameter. For example, you can request gmail.send + gmail.labels together. However, combining scopes increases the permissions shown on Google's consent screen and may trigger additional verification requirements if any combined scope is restricted. Always request only the minimum combination your app genuinely needs. For the Microsoft side, see Microsoft Graph OAuth scopes equivalent.gmail.metadata scope is a restricted gmail api scope that grants access to email headers and labels only, without any access to email body content or attachments. It is useful for routing engines, categorization systems, or analytics tools that process emails based on sender, recipient, subject, or labels without reading private message content. Despite being restricted, it has a narrower data footprint than gmail.readonly and may be easier to justify in a security assessment. We dive deeper in our email sync API for full inbox sync.gmail.send scope is a sensitive gmail api scope that allows your app to send emails on behalf of an authenticated user, without granting read or modify access to existing messages. It is the recommended minimum scope for apps that only send emails - outreach tools, notification systems, or follow-up automation. Using gmail.send instead of gmail.modify avoids the restricted scope security assessment entirely, significantly accelerating your path to production. See our dedicated Send Email API guide.
EN 
FR 
ES 
DE 
IT 
BR 
NL 
PL 
TR