{"slug":"gmail","name":"Gmail","domain":"google.com","category":"Email","summary":"You can connect your own account and up to 100 test users the same day. The scopes most Gmail integrations need (gmail.readonly, gmail.modify, gmail.compose) are restricted, so a public launch needs Google's OAuth verification and a paid, annual third-party CASA security assessment. Expect several weeks.","tier":"gated","tierReason":"Typical Gmail scopes are restricted, and Google requires a paid third-party CASA security assessment (assessor fees of about $500–$4,500, renewed every year) before the public can connect.","quality":"researched","updatedAt":"2026-10-27","composio":{"status":"managed","note":"Composio has a managed Gmail OAuth app, so you can prototype without registering your own. To have your own name on the consent screen, you have to register your own app and go through Google's verification and CASA yourself.","toolkit":"GMAIL"},"totals":{"effort":{"min":3,"max":10,"unit":"days"},"wait":{"min":2,"max":8,"unit":"weeks"},"firstConnection":"Today, in about 30–60 minutes, with your own account added as a test user"},"stages":[{"id":"build","name":"Your account","whoCanConnect":"You, added as a test user on an External app in Testing status, or anyone in your Workspace org if the app is Internal.","userSees":"A Google 'hasn't verified this app' warning before consent. Grants expire after 7 days.","effort":{"min":30,"max":60,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":"Add other Google accounts to the test-user list.","evidence":{"kind":"docs","sources":["s3","s4"],"confidence":"high"}},{"id":"beta","name":"Test users","whoCanConnect":"Up to 100 test users you list by email. Each one counts against a quota that does not reset.","userSees":"An unverified-app warning. Grants and refresh tokens expire 7 days after consent, so users have to reconnect weekly.","effort":{"min":5,"max":15,"unit":"minutes"},"wait":{"min":0,"max":0,"unit":"minutes"},"unlock":"Publish to production, submit for verification, pass restricted-scope review and the CASA security assessment.","evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"id":"launch","name":"Public launch","whoCanConnect":"Any Google account.","userSees":"A normal consent screen with your app name and logo, listing the Gmail permissions requested.","effort":{"min":3,"max":10,"unit":"days"},"wait":{"min":2,"max":8,"unit":"weeks"},"unlock":null,"evidence":{"kind":"community","sources":["s5","s6","s8","s9"],"confidence":"medium"}}],"requirements":[{"id":"google-account","label":"Google account and Google Cloud project","detail":"Any Google account can create a Cloud project. Internal apps need a Google Cloud Organization, which comes from Workspace or Cloud Identity.","stage":"build","actor":"you","evidence":{"kind":"docs","sources":["s4","s7"],"confidence":"high"}},{"id":"owned-domain","label":"Verified domain you own","detail":"Your homepage, privacy policy and redirect domains must be authorized domains, verified in Google Search Console.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s7","s9"],"confidence":"high"}},{"id":"homepage-privacy","label":"Public homepage and privacy policy","detail":"The homepage must be public, not behind a login. The privacy policy must include the Google API Services Limited Use disclosure and explain how Gmail data is handled.","stage":"launch","actor":"you","evidence":{"kind":"community","sources":["s9","s7"],"confidence":"medium"}},{"id":"demo-video","label":"Demo video","detail":"An English video showing the full OAuth flow, the consent screen with the exact scopes requested, and each feature that uses each scope.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s2","s7"],"confidence":"high"}},{"id":"casa","label":"CASA security assessment (paid, annual)","detail":"Required if you store or transmit restricted-scope data on servers. A Google-empanelled assessor does it. You pay the assessor about $500–$4,500, and the Letter of Validation must be renewed every 12 months.","stage":"launch","actor":"you","evidence":{"kind":"docs","sources":["s1","s5","s6"],"confidence":"high"}}],"steps":[{"id":"create-project","title":"Create a Google Cloud project","actor":"you","stage":"build","time":{"min":5,"max":10,"unit":"minutes"},"detail":"Sign in to the Google Cloud console and create a project for the app. Google recommends separate projects for development and production.","actions":["Sign in at console.cloud.google.com","Create a new project and name it"],"agentNote":"Once you're signed in, an agent can create the project.","gotcha":"The 100-user unverified cap applies for the project's lifetime and never resets, so keep test traffic in a separate dev project.","link":{"label":"Google Cloud console","url":"https://console.cloud.google.com/projectcreate"},"evidence":{"kind":"docs","sources":["s7","s8"],"confidence":"high"}},{"id":"enable-gmail-api","title":"Enable the Gmail API","actor":"agent","stage":"build","time":{"min":2,"max":5,"unit":"minutes"},"detail":"In the API Library, find the Gmail API and enable it for the project.","actions":["APIs & Services > Library > Gmail API > Enable"],"agentNote":"An agent can do this in the console.","link":{"label":"Gmail API in API Library","url":"https://console.cloud.google.com/apis/library/gmail.googleapis.com"},"evidence":{"kind":"docs","sources":["s7"],"confidence":"high"}},{"id":"configure-consent","title":"Configure the OAuth consent screen","actor":"agent","stage":"build","time":{"min":10,"max":20,"unit":"minutes"},"detail":"In Google Auth Platform, set the user type to External (or Internal for your org only) and fill in branding: app name, support email, logo, homepage, privacy policy, terms, authorized domains and developer contact.","actions":["Choose user type: External or Internal","Fill in app name, user support email and developer contact email","Add homepage, privacy policy and terms URLs","Add authorized domains"],"agentNote":"An agent can fill in the form. You choose the support and contact emails.","gotcha":"Use a contact inbox someone monitors. Google sends all verification messages there.","link":{"label":"Google Auth Platform – Branding","url":"https://console.cloud.google.com/auth/branding"},"evidence":{"kind":"docs","sources":["s7","s4"],"confidence":"high"}},{"id":"add-scopes","title":"Add the narrowest Gmail scopes you need","actor":"agent","stage":"build","time":{"min":5,"max":10,"unit":"minutes"},"detail":"On the Data Access page, add only the scopes your live features use. gmail.send is sensitive. gmail.readonly, gmail.modify, gmail.compose, gmail.metadata and https://mail.google.com/ are restricted.","actions":["Data Access > Add or remove scopes","Pick the narrowest scope that works, for example gmail.send for send-only apps"],"agentNote":"An agent can add the scopes once you've decided which ones you need.","gotcha":"Scopes on the consent screen must match what your app actually requests. A mismatch is a common reason for rejection.","link":{"label":"Google Auth Platform – Data Access","url":"https://console.cloud.google.com/auth/scopes"},"evidence":{"kind":"docs","sources":["s2","s9"],"confidence":"high"}},{"id":"create-client","title":"Create a Web application OAuth client","actor":"agent","stage":"build","time":{"min":5,"max":10,"unit":"minutes"},"detail":"Create an OAuth client ID of type Web application and add your redirect URI under Authorized redirect URIs. A person should copy the client secret into your OAuth client's configuration.","actions":["Clients > Create client > Web application","Add your redirect URI exactly as your OAuth client sends it","You copy the client ID and secret into your OAuth client"],"agentNote":"An agent can create the client and enter your redirect URI. It hands off to you before the secret is shown.","gotcha":"Request access_type=offline and prompt=consent so you get a refresh token.","link":{"label":"Google Auth Platform – Clients","url":"https://console.cloud.google.com/auth/clients"},"evidence":{"kind":"docs","sources":["s7"],"confidence":"high"}},{"id":"add-test-users","title":"Add test users and connect","actor":"agent","stage":"build","time":{"min":5,"max":15,"unit":"minutes"},"detail":"While the app is in Testing status, add your account and up to 99 others under Audience > Test users, then run a test connection through your OAuth client.","actions":["Audience > Test users > Add users","Connect your own account through your OAuth client and call the Gmail API"],"agentNote":"An agent can add the emails and run a test connection. You sign in to Google during consent.","gotcha":"In Testing, grants and refresh tokens expire after 7 days, and each test user permanently uses up one of the 100 slots.","link":{"label":"Google Auth Platform – Audience","url":"https://console.cloud.google.com/auth/audience"},"evidence":{"kind":"docs","sources":["s4","s9"],"confidence":"high"}},{"id":"verify-domain","title":"Verify domain ownership in Search Console","actor":"you","stage":"launch","time":{"min":15,"max":60,"unit":"minutes"},"detail":"Verify the domains for your homepage, privacy policy and redirect URIs in Google Search Console, using an account that is an owner or editor on the project.","actions":["Add a DNS TXT record or use another Search Console verification method"],"agentNote":"An agent can start the Search Console flow. You make the DNS change.","gotcha":"An unverified callback or homepage domain is a common rejection reason.","link":{"label":"Google Search Console","url":"https://search.google.com/search-console"},"evidence":{"kind":"community","sources":["s9"],"confidence":"medium"}},{"id":"prepare-submission","title":"Record demo video and write justifications","actor":"you","stage":"launch","time":{"min":3,"max":8,"unit":"hours"},"detail":"Record an English demo showing the consent screen with the exact scopes and every feature that uses each scope. For each scope, write which feature uses it and why a narrower scope won't work.","actions":["Upload the video as unlisted on YouTube","Draft a justification for each scope","Add the Limited Use disclosure to your privacy policy"],"agentNote":"An agent can draft justifications. You record the video.","gotcha":"Vague justifications and videos that don't show the real consent screen are the most common reasons for resubmission.","evidence":{"kind":"docs","sources":["s2","s7","s9"],"confidence":"high"}},{"id":"submit-verification","title":"Publish the app and submit for verification","actor":"you","stage":"launch","time":{"min":30,"max":60,"unit":"minutes"},"detail":"Click Publish app to move to production, then use Prepare for verification in the Verification Center, add the justifications and video link, and submit.","actions":["Audience > Publish app","Verification Center > Prepare for verification > Submit"],"agentNote":"An agent can fill in the forms. You submit.","gotcha":"If you change anything after submitting, you have to resubmit the form or review stalls.","link":{"label":"Verification Center","url":"https://console.cloud.google.com/auth/verification"},"evidence":{"kind":"docs","sources":["s7"],"confidence":"high"}},{"id":"trust-safety-review","title":"Wait for Trust & Safety review","actor":"provider","stage":"launch","time":{"min":3,"max":14,"unit":"days"},"detail":"Google's OAuth review team emails project owners and editors, often within 24–48 hours, and may ask for changes. Approval of the use case often comes in under a week, and Google's own estimate is several weeks.","gotcha":"Reply within a day. Each back-and-forth adds days.","evidence":{"kind":"community","sources":["s9","s8"],"confidence":"medium"}},{"id":"casa-assessment","title":"Complete the CASA security assessment","actor":"you","stage":"launch","time":{"min":2,"max":5,"unit":"days"},"detail":"When Google tells you to start, hire an empanelled CASA assessor (most apps are Tier 2), fix any scan findings and get a Letter of Validation. Assessor fees run about $500–$4,500.","actions":["Choose an assessor from the App Defense Alliance list","Run SAST/DAST scans and answer the questionnaire","Fix findings and get the Letter of Validation"],"agentNote":"An agent can help prepare the questionnaire answers. You pay and deal with the assessor.","gotcha":"Pick an assessor early. Tier 3 (for example, with domain-wide delegation) costs much more.","link":{"label":"App Defense Alliance CASA","url":"https://appdefensealliance.dev/casa"},"evidence":{"kind":"docs","sources":["s5","s6","s9"],"confidence":"high"}},{"id":"casa-wait","title":"Wait for CASA and final approval","actor":"provider","stage":"launch","time":{"min":2,"max":4,"unit":"weeks"},"detail":"Google says Tier 2 assessments take 2–3 weeks. After the Letter of Validation, Google may take up to a week to grant final approval.","gotcha":"Restricted-scope verification and CASA must be renewed every 12 months. Start 60–90 days before expiry.","evidence":{"kind":"docs","sources":["s6","s9","s1"],"confidence":"medium"}}],"scopes":{"intro":"Google classifies Gmail scopes into three levels. The level decides what review you go through. Most read or modify integrations need restricted scopes.","tiers":[{"scope":"gmail.labels","grants":"View and edit labels","level":"basic","consequence":"Brand verification only, if you want your name and logo shown"},{"scope":"gmail.send","grants":"Send email as the user","level":"sensitive","consequence":"OAuth app verification (demo video, justification). No CASA."},{"scope":"gmail.readonly / gmail.metadata","grants":"Read messages and settings, or headers and labels only","level":"restricted","consequence":"Restricted-scope verification plus annual CASA assessment if data reaches your servers"},{"scope":"gmail.modify / gmail.compose / gmail.insert / gmail.settings.basic","grants":"Read, write, send, drafts and settings","level":"restricted","consequence":"Restricted-scope verification plus annual CASA assessment"},{"scope":"https://mail.google.com/","grants":"Full mailbox access, including permanent delete","level":"restricted","consequence":"Restricted review. Google asks you to request it only if you need permanent deletion."}]},"blockers":[{"symptom":"Users see 'Google hasn't verified this app' and new sign-ups stop after 100 users","cause":"The app is unverified and uses sensitive or restricted scopes. The 100-user cap applies for the project's lifetime and cannot be reset.","fix":"Complete verification. Keep development in a separate project so you don't use up the production quota.","evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"symptom":"invalid_grant on refresh after about a week","cause":"In Testing status, grants and refresh tokens expire 7 days after consent.","fix":"Have users reconnect, or publish to production and get verified.","evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"symptom":"Error 403: org_internal","cause":"The app's user type is Internal, and the user is outside your Google Cloud organization.","fix":"Switch the user type to External.","evidence":{"kind":"docs","sources":["s4"],"confidence":"high"}},{"symptom":"Verification sent back for resubmission","cause":"Common causes: scope mismatch, unused scopes, weak demo video, vague justifications, homepage behind a login, missing Limited Use disclosure.","fix":"Fix every listed issue, re-record the video if needed and resubmit the form.","evidence":{"kind":"community","sources":["s9"],"confidence":"medium"}}],"unknowns":[{"question":"Exact end-to-end time for Gmail restricted-scope approval","why":"Google gives no Gmail-specific timeline. The CASA figures come from a Google Health API page, and the rest from vendor reports.","resolve":"Watch the Verification Center and the emails Google sends to your contact address after you submit."},{"question":"Which CASA tier and fee your app will get","why":"Google assigns the tier based on user count, scopes and other risk signals.","resolve":"Google Trust & Safety tells you the tier when the assessment starts. Ask assessors for quotes."},{"question":"Whether you can skip CASA by keeping all Gmail data on the client","why":"The docs say the assessment applies when restricted data is stored or transmitted on servers, but Google decides each case during review.","resolve":"Describe your data flow in the submission and confirm with the review team."}],"handoff":{"agentCan":["Enable the Gmail API","Fill in the consent screen branding and Data Access scopes","Create the Web OAuth client and enter your redirect URI","Add test users and run a test connection","Draft scope justifications and CASA questionnaire answers"],"youMust":["Sign in and create the Google Cloud project","Copy the client secret into your OAuth client","Verify domains in Search Console","Record the demo video","Submit for verification and answer Google's emails","Pay for and complete the CASA assessment every year"]},"sources":[{"id":"s1","title":"Restricted scope verification","url":"https://support.google.com/cloud/answer/13464321","publisher":"Google Cloud Help","kind":"official","checkedAt":"2026-10-27"},{"id":"s2","title":"Choose Gmail API scopes","url":"https://developers.google.com/workspace/gmail/api/auth/scopes","publisher":"Google for Developers","kind":"official","checkedAt":"2026-10-27"},{"id":"s3","title":"When is verification not needed","url":"https://support.google.com/cloud/answer/13464323","publisher":"Google Cloud Help","kind":"official","checkedAt":"2026-10-27"},{"id":"s4","title":"Manage app audience","url":"https://support.google.com/cloud/answer/15549945","publisher":"Google Cloud Help","kind":"official","checkedAt":"2026-10-27"},{"id":"s5","title":"Security assessment","url":"https://support.google.com/cloud/answer/13465431","publisher":"Google Cloud Help","kind":"official","checkedAt":"2026-10-27"},{"id":"s6","title":"App verification (Google Health API)","url":"https://developers.google.com/health/app-verification","publisher":"Google for Developers","kind":"official","checkedAt":"2026-10-27"},{"id":"s7","title":"Submitting your app for verification","url":"https://support.google.com/cloud/answer/13461325","publisher":"Google Cloud Help","kind":"official","checkedAt":"2026-10-27"},{"id":"s8","title":"OAuth App Verification overview","url":"https://support.google.com/cloud/answer/13463073","publisher":"Google Cloud Help","kind":"official","checkedAt":"2026-10-27"},{"id":"s9","title":"Google security review","url":"https://nango.dev/docs/api-integrations/google-shared/google-security-review","publisher":"Nango docs","kind":"community","checkedAt":"2026-10-27"},{"id":"s10","title":"Managed auth toolkits","url":"https://docs.composio.dev/toolkits/managed-auth.md","publisher":"Composio docs","kind":"composio","checkedAt":"2026-10-27"}],"feedback":{}}