Does the Gmail API use an API key or OAuth?

OAuth, not an API key. You create a Google Cloud OAuth client, authorize the Gmail scopes in the OAuth Playground, and exchange them for a refresh token. Outloop stores the OAuth credential locally in macOS Keychain and mints short-lived access tokens host-side; the agent never sees any part of it.

What can an AI agent do in Gmail through Outloop?

With the full mailbox workflow tier: read messages and mailbox metadata, organize with labels, create drafts, and send email — each action gated by the OAuth scope you authorized and by Outloop runtime policy. Hard deletes and mailbox settings changes (forwarding, filters, delegates) stay blocked.

Can my agent see the Gmail refresh token or client secret?

No. Outloop stores the OAuth parts once in macOS Keychain and uses them host-side through the API Bridge — minting a short-lived access token and injecting the Authorization header itself, so the credential is used on the wire without the agent ever seeing it. Every request is audited with secret_exposed: false.

Can agents delete emails or change mailbox settings?

No. Hard deletes and mailbox settings changes (forwarding, filters, delegates) stay blocked by Outloop runtime policy. Google adds its own layer: the gmail.modify scope does not allow permanently deleting messages past the trash.

Why did my refresh token stop working after a week?

If the Google Cloud OAuth consent screen is in Testing status with an External user type, Google revokes refresh tokens after 7 days. Publish the app to In production (or use an Internal user type in a Google Workspace organisation) and generate a new refresh token.

Is there an official Gmail MCP server?

Yes — Google offers a remote Gmail MCP server (Google Workspace Developer Preview) with tools for drafts, thread search, and labels. Its documented toolset has no send tool, and it is not connected in this workspace, so this guide does not mark MCP capabilities as verified; the Gmail API through Outloop is what is live and verified here.

Learn · Setup guides

How to Connect Gmail API to AI Agents with Outloop

Last updated: July 2, 2026

In short

Gmail uses OAuth, not an API key — and Outloop keeps the whole OAuth credential away from the agent.

You enable the Gmail API, add the Gmail scopes, create one Google Cloud OAuth client, and exchange it for a refresh token in the OAuth Playground. Outloop stores the OAuth parts locally in macOS Keychain, and agents read mailbox data, organize messages, create drafts, and send email only through the secure API Bridge — without ever seeing the client secret, refresh token, or access token.

Summarize this setup guide with AI ChatGPT Claude Perplexity

What this setup gives you

You will enable the Gmail API in Google Cloud, add the Gmail OAuth scopes, create an OAuth client for the OAuth Playground, generate a refresh token, and store the credential in Outloop. After that, AI agents can run the full mailbox workflow — read mailbox data, organize messages, create drafts, and send email — when you grant the matching Gmail scopes. Outloop stores the OAuth parts locally and lets agents access Gmail only through the secure API Bridge; the raw credential never appears to the agent, in chat, logs, repos, or project files.

Security rule. Never record, screenshot, paste, or publish a real client_secret, refresh_token, access_token, authorization code, or Authorization header. Their only destination is the Outloop Mac app — never Outloop Cloud, the website, chat, docs, or .env files. Every screenshot in this guide has the credential fields redacted.

What you need before starting

✓Access to a Google Cloud project with the OAuth consent screen configured.
✓The Google account / mailbox you want agents to work with.
✓Outloop installed and activated, with a workspace selected.

1. Enable the Gmail API

In Google Cloud Console, open APIs & Services → Library, search Gmail API, and click Enable. The product page confirms with a green API Enabled badge (service name gmail.googleapis.com). The scope panel in the next step only lists scopes for APIs that are already enabled, so do this first.

2. Add the Gmail OAuth scopes

In Google Auth Platform → Data access, click Add or remove scopes.

Google Auth Platform Data access page with the Add or remove scopes button highlighted for the Gmail API.

Tick the four Gmail scopes in the table (or paste any missing ones into Manually add scopes), click Add to table, then Update:

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.compose
https://www.googleapis.com/auth/gmail.send

Add Gmail OAuth scopes for the full mailbox workflow — readonly, modify, compose, and send ticked, with manually added scopes and the Update button.

What each scope unlocks. Together these four cover the full mailbox workflow: gmail.readonly — read messages and settings; gmail.modify — organize (labels, archive); gmail.compose — manage drafts; gmail.send — send mail. Google classes readonly, modify, and compose as restricted scopes and send as a sensitive scope — expect the unverified-app warning during authorization until the consent screen is verified. If your agents only need part of the workflow, authorize the narrower subset.

3. Create the OAuth client

In Google Auth Platform → Clients, create a new OAuth client. Choose Application type: Web application, name it Outloop OAuth Playground - Gmail, and under Authorised redirect URIs add the OAuth Playground URL:

https://developers.google.com/oauthplayground

Create OAuth Playground web client for Gmail API — Web application type, Outloop OAuth Playground Gmail name, and the OAuth Playground redirect URI.

Use Web application. Do not choose Desktop app for this refresh-token generation flow — the OAuth Playground only works as a redirect URI on a Web application client.

Click Create. The confirmation dialog shows the Client ID and Client secret — copy both now; the secret is not shown again after you close the dialog.

OAuth client created dialog in Google Cloud for the Gmail client with the client ID and client secret values redacted.

4. Get a refresh token (OAuth Playground)

Open developers.google.com/oauthplayground and click the gear icon:

→Check Use your own OAuth credentials.
→Set Access type: Offline and Force prompt: Consent Screen.
→Paste the OAuth Client ID and Client Secret from step 3 (do not screenshot the pasted values).
→In Step 1, paste the four Gmail scopes into Input your own scopes and click Authorize APIs.
→Sign in with the Gmail account you want agents to work with and approve the consent screen.

Authorize Gmail API scopes in OAuth Playground — own OAuth credentials enabled, Offline access, Consent Screen prompt, Gmail scopes pasted, and the credential fields redacted.

The Playground returns to Step 2 with an authorization code. Click Exchange authorization code for tokens and copy the refresh_token — its only destination is the Outloop Mac app. The access token you can ignore; Outloop mints its own.

Exchange Gmail authorization code for refresh token in OAuth Playground with the token values redacted.

5. Add Gmail in Outloop

In Outloop, open API Keys & Access → Add Access, search gmail, and choose Gmail under Google Workspace Pack (it is an OAuth service, not a paste-one-key service). Pick the workspace scope — shared / global works well when several workspaces will use the same mailbox credential.

Select Gmail under Google Workspace Pack in Outloop when adding API access.

6. Enter the Gmail OAuth details

Paste the values you collected, then click Set up Gmail OAuth:

→Client ID and Client Secret from Google Cloud (step 3).
→Refresh Token from the OAuth Playground (step 4).
→OAuth scope tier — select Full mailbox workflow — read, drafts, organize + send mail to match the four scopes you authorized. The tier you pick is what agents can do through Outloop.

Set up Gmail OAuth credential in Outloop — client ID redacted, client secret and refresh token masked, and the Full mailbox workflow scope tier selected.

Stored. Outloop stores the OAuth parts once in macOS Keychain — never shown again, agents never see them. Turn on Runtime access on the Gmail key row to let agents use the credential.

7. macOS Keychain: click Always Allow

When macOS asks for Keychain access, click Always Allow. If you click Deny or only Allow once, agents may not be able to use the credential reliably at runtime — the prompt reappears on every read and a dismissed prompt fails the request even though the credential is stored correctly.

macOS Keychain Always Allow prompt for Outloop runtime access, with the Always Allow button highlighted.

Local only. This is macOS asking, not Outloop Cloud — the credential is read host-side from your Mac's Keychain at request time and is never uploaded.

8. Runtime proof

In a real runtime proof, Outloop successfully called Gmail through the secure API Bridge — a safe read of the mailbox profile, run by an agent that never saw the credential:

service: gmail
decision / code: allow / OK
HTTP status: 200
secret_exposed: false
runtime-verified: yes

Gmail API runtime proof with secret_exposed false — decision allow, HTTP 200, service gmail, and runtime-verified yes, with identifiers redacted.

The setup is complete when the proof shows runtime-verified: yes and secret_exposed: false. Your agent can now use Gmail through Outloop; the OAuth credential stays in macOS Keychain.

What the agent never sees

✓Agents never see the OAuth Client Secret, refresh token, access token, or Authorization headers.
✓Outloop mints short-lived access tokens host-side and injects the headers itself — the credential is used on the wire, never handed to the agent.
✓Every runtime request is audited, and results are redacted.
✓Hard deletes and mailbox settings / admin changes (forwarding, filters, delegates) stay blocked by runtime policy.
✓Gmail send is allowed only when both the OAuth scope you authorized and Outloop policy allow it.

What the Gmail API can do through Outloop

Reads

✓Mailbox profile and metadata, message and thread listing and search (users.messages, users.threads), label listing.

Writes (gated by scope + policy)

✓Create and update drafts (users.drafts) under gmail.compose.
✓Organize: add/remove labels, archive, mark read/unread (users.messages.modify) under gmail.modify.
✓Send mail (users.messages.send) under gmail.send.

Blocked by Outloop runtime policy

✕Hard deletes (Google's own gmail.modify scope also cannot permanently delete past the trash).
✕Mailbox settings and admin changes — forwarding, filters, delegates.

Verified vs not claimed yet

Verified Gmail read access through Outloop: a safe mailbox-profile read returned decision allow / OK, HTTP 200, secret_exposed: false, runtime-verified: yes, with an audit entry.
Supported, not verified yet Drafts, organize, and send: supported by the API and permitted through bridge policy under the authorized scopes, but not runtime-verified in this guide. The safest first write to test is creating a draft — it changes nothing in anyone's inbox.
Not claimed Hard deletes and mailbox settings / admin changes are blocked by runtime policy — this guide makes no claim that agents can perform them through Outloop.

Gmail API through Outloop vs the Gmail MCP

Google offers a remote Gmail MCP server (currently part of the Google Workspace Developer Preview Program) with tools for drafts, thread search, and labels. MCP can be a useful path; the comparison below is specific to Gmail and to what is actually live in this workspace.

For this workspace, the Gmail API through Outloop is the only Gmail path that is live and verified right now.
Area	Gmail API through Outloop	Gmail MCP
Live in this workspace	Live now The API path is the only Gmail path connected here.	Not connected here Google offers a remote Gmail MCP server (Google Workspace Developer Preview), but it is not connected in this workspace.
Verified in this guide	Verified in this guide Proven with a real Gmail read proof through Outloop (allow / OK, HTTP 200, secret_exposed: false, runtime-verified: yes).	Not verified here
Auth model	OAuth client + refresh token stored in macOS Keychain; Outloop mints short-lived access tokens host-side.	OAuth 2.0 session between the AI application and Google (gmail.readonly + gmail.compose); token handling depends on the client.
Raw secret exposure to the agent	Secret-safe The credential is used on the wire; the agent never sees the client secret, refresh token, access token, or Authorization header.	Depends on the connector/OAuth session model.
Audit trail	Audited Every API Bridge request is auditable through Outloop, with redacted results.	Not through Outloop.
Workspace / client routing	Workspace-scoped The credential is granted per workspace; wrong-client access is blocked by policy.	Not through Outloop.
Read actions	Full Gmail API v1 reads under the authorized scope: messages, threads, labels, mailbox profile and metadata.	search_threads, get_thread, list_drafts, list_labels.
Write actions	Drafts, label/organize operations, and send — each gated by the authorized scope and Outloop runtime policy. Hard deletes and mailbox settings changes stay blocked.	create_draft, label/unlabel operations, create_label. The documented toolset has no send tool.

Honesty note. This comparison is intentionally conservative. The official Gmail MCP server exposes a documented toolset, but it is not connected in this workspace, so this guide does not mark MCP capabilities as verified. By contrast, the Outloop API Bridge path is live and verified here.

Troubleshooting

The refresh token stops working after 7 days

If the OAuth consent screen's publishing status is Testing with an External user type, Google revokes refresh tokens after 7 days. In Google Auth Platform → Audience, publish the app to In production (or use an Internal user type in a Google Workspace organisation), then generate a new refresh token and update it in Outloop.

I do not see a refresh token in the Playground

Confirm Use your own OAuth credentials is checked, Access type is Offline, Force prompt is Consent Screen, and the redirect URI in Google Cloud is exactly https://developers.google.com/oauthplayground. Then authorize again.

Google warns the app is unverified during authorization

Expected for restricted Gmail scopes on an unverified consent screen. For your own account and a test setup, continue through the advanced option; for broader use, complete Google's consent-screen verification.

The proof returns 403

Usually the authorized scopes do not cover the request (for example, a send attempt with only gmail.readonly authorized), or the scope tier picked in Outloop does not match what you authorized in the Playground. Re-authorize with the right scopes and match the tier.

Runtime access fails even though the key is stored

Check the macOS Keychain prompt was answered with Always Allow (step 7) and that Runtime access is turned on for the Gmail key row in Outloop.

Outloop is available with guided onboarding for agency teams. Outloop is an independent tool and is not affiliated with or endorsed by Google. See the security model, the Google Drive setup guide, or the Google Analytics GA4 setup guide.