# Gmail setup for PopMCP

You end up pasting a Google OAuth Client ID and Client Secret from a Web application client you register in the Google Cloud console, with the three Gmail scopes added on its Data access page.

- Auth: OAuth authorization
- Setup time: 12 min
- API base URL: https://gmail.googleapis.com/gmail/v1
- Credentials screen: https://console.cloud.google.com/auth/clients
- Provider docs: https://developers.google.com/workspace/gmail/api/guides

## Approval required before this works

Every useful Gmail scope is classified restricted (mail.google.com, gmail.readonly, gmail.modify, gmail.compose, gmail.insert, gmail.metadata, gmail.settings.basic, gmail.settings.sharing), so Google must verify your OAuth client before it can leave Testing. Because a connector moves that data through a third-party server, Google additionally requires an annual CASA security assessment by a Google-empanelled assessor.

- Typical wait: Google says restricted scope verification 'can potentially take several weeks to complete'. Brand verification alone is 2-3 business days. Recertification is required at least every 12 months from your assessor's Letter of Assessment approval date.
- Cost: Google charges nothing for verification itself and publishes no price for the assessment. The CASA assessment is paid to a third-party App Defense Alliance assessor who sets its own fee; third-party writeups commonly report Tier 2 quotes in the mid-hundreds to low-thousands of USD per year, with Tier 3 and large-vendor engagements higher. Treat any specific figure as a quote to confirm with an assessor, not a list price.
- Blocked until approved: Until verification lands the OAuth client stays in Testing publishing status: only hand-added test users can consent (the Cloud console caps this at 100), every one of them sees the unverified-app warning screen, and Google issues refresh tokens that expire in 7 days for External-type clients, so the connector dies with invalid_grant roughly weekly. You cannot onboard arbitrary end users at all.
- Works meanwhile: Everything works fully for the hand-added test users, provided they re-consent weekly. Documented paths that skip verification entirely: an Internal-type app in a Google Workspace or Cloud Identity organisation, where restricted and sensitive scopes need no Google review (a service account with domain-wide delegation covers server-to-server Workspace mailbox access the same way); an app used only by yourself or a small group of people you know personally, which stays unverified and keeps the warning screen; and gmail.send alone, which is only a sensitive scope, so it needs standard verification (Google states 3-5 business days) and no CASA.

## Before you begin

- A Google account, plus a Google Cloud project you own (free, no billing card needed)
- Owner or Editor role on that Cloud project. Viewer cannot create OAuth clients
- The PopMCP callback URL from the Gmail connect form. Copy it before you start
- Willingness to publish the app. An External app left in Testing gets a refresh token Google expires after 7 days, and all three Gmail scopes here are restricted
- Personal Gmail accounts can only use the External audience. Internal requires a Google Workspace organisation

## Get your credentials

### 1. Create a Cloud project and enable the Gmail API

Pick or create a project in the Cloud console, then go to APIs & Services → Library and search for Gmail API. Open its card and click Enable.

Screen: https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com

### 2. Fill in the consent screen under Google Auth Platform

Open Google Auth Platform → Branding and enter App name, User support email and a developer contact address, then click Save. Choose External as the user type unless everyone using this connector sits inside your Workspace organisation.

Screen: https://console.cloud.google.com/auth/branding

### 3. Add the three Gmail scopes on Data access

Go to Data access and click Add or remove scopes. Paste `https://mail.google.com/`, `https://www.googleapis.com/auth/gmail.settings.basic` and `https://www.googleapis.com/auth/gmail.settings.sharing` into the Manually add scopes box, click Add to table, then Update and Save.

Screen: https://console.cloud.google.com/auth/scopes

### 4. Publish the app on the Audience page

Open Audience and check Publishing status. If it reads Testing, click Publish app and confirm.

Screen: https://console.cloud.google.com/auth/audience

### 5. Create a Web application OAuth client

Click Clients → Create client and set Application type to Web application. Under Authorized redirect URIs click Add URI, paste the callback URL from PopMCP's Gmail connect form exactly as shown, then click Create.

Screen: https://console.cloud.google.com/auth/clients/create

### 6. Copy the client ID and secret into PopMCP

Copy Client ID and Client secret from the OAuth client created dialog into PopMCP's OAuth Client ID and OAuth Client Secret fields. If the dialog is already gone, open the client and click Add secret.

## Fields PopMCP asks for

- OAuth Client ID (clientId) [required]: Google Cloud Console → Google Auth Platform → Clients → Create client → Web application, with the callback URL above under Authorized redirect URIs. Enable the Gmail API on the same project first (APIs & Services → Library → Gmail API → Enable), or the Gmail permissions won't be offered.
- OAuth Client Secret (clientSecret) [required]: Shown once, in the popup right after you create the client. Google hashes it and never shows it again; if you closed that popup, open the client and add a new secret. Stored encrypted here and used server-side only. TWO THINGS TO CHECK FIRST: (1) In Google Auth Platform → Data access, add all three Gmail scopes — https://mail.google.com/, gmail.settings.basic and gmail.settings.sharing. (2) In Google Auth Platform → Audience, if the status says "Testing", click "Publish app". Testing-mode apps get a refresh token Google expires after exactly 7 days, so the connection would work for a week and then stop. Publishing needs no Google review; it only adds a one-time "Google hasn't verified this app" screen where you click Advanced and continue.

## Callback URL to register

https://app.popmcp.com/api/providers/google/callback

## Scopes requested

- https://mail.google.com/
- https://www.googleapis.com/auth/gmail.settings.basic
- https://www.googleapis.com/auth/gmail.settings.sharing

## Verify

In PopMCP, click Connect, choose the Google account, pass the "Google hasn't verified this app" screen via Advanced → Go to (app), and tick all requested Gmail permissions. The connector shows Connected and a message-search tool returns real threads from the inbox.

## Troubleshooting

### Error 400: redirect_uri_mismatch

Cause: The Authorized redirect URI does not byte-for-byte match the callback URL PopMCP uses.

Fix: Re-copy the callback URL from the PopMCP connect form into Clients → your client → Authorized redirect URIs and save. Allow a couple of minutes to propagate.

### invalid_grant after about a week

Cause: The app is still in Testing, so Google expires the refresh token seven days after consent.

Fix: Go to Google Auth Platform → Audience → Publish app, then reconnect in PopMCP.

### The consent screen never asks for the settings permissions

Cause: gmail.settings.basic and gmail.settings.sharing were not added on the Data access page.

Fix: Add both scopes under Data access → Add or remove scopes → Manually add scopes, click Update and Save, then disconnect and reconnect so consent is re-requested.

### Scopes do not appear in the picker on Data access

Cause: Only scopes belonging to enabled APIs are listed, and the Gmail API is off on this project.

Fix: Enable Gmail API under APIs & Services → Library, then reopen Data access.

### 429 or 403 rateLimitExceeded during a large sync

Cause: The ceiling of 6,000 quota units per minute per user per project was hit. A single messages.send costs 100 units, so bulk work burns through it quickly.

Fix: Let the connector back off and retry. Spread bulk operations out rather than requesting a full mailbox scan at once.

---

Source: https://www.docs.popmcp.com/docs/integrations/gmail/