---
title: Gmail | Keycard
description: Access Gmail emails and send messages
---

[Google developer console](https://console.cloud.google.com/apis/credentials)[OAuth setup guide](https://developers.google.com/identity/protocols/oauth2)[API docs](https://developers.google.com/gmail/api/guides)

Adding Gmail provisions a resource (the upstream Google API at `https://gmail.googleapis.com`, with default scopes pre-set) and a provider for Google’s OAuth issuer - auto-provisioned on first install, or reused if you already connected another Google resource.

Your application calls Keycard’s [token-exchange endpoint](/sdk/oauth/index.md) with the user’s identity, gets back a token scoped to this resource, and uses it to call Google directly. Identity, [policy](/admin/access-policies/index.md), and audit log apply to every exchange - the OAuth client secret stays inside Keycard. Each exchange is recorded in the audit log with the user identity, the resource accessed, and the policy decision.

## Scopes

SCOPES

OAuth permissions Keycard requests on install. Override or add scopes in Console.

- https\://www\.googleapis.com/auth/gmail.readonly

  default

- https\://www\.googleapis.com/auth/gmail.send

  default

- https\://www\.googleapis.com/auth/gmail.labels

- https\://www\.googleapis.com/auth/gmail.compose

- https\://www\.googleapis.com/auth/gmail.insert

- https\://www\.googleapis.com/auth/gmail.modify

- https\://www\.googleapis.com/auth/gmail.metadata

- https\://www\.googleapis.com/auth/gmail.settings.basic

- https\://www\.googleapis.com/auth/gmail.settings.sharing

- https\://www\.googleapis.com/auth/gmail.addons.current.action.compose

- https\://www\.googleapis.com/auth/gmail.addons.current.message.action

- https\://www\.googleapis.com/auth/gmail.addons.current.message.metadata

- https\://www\.googleapis.com/auth/gmail.addons.current.message.readonly

- https\://mail.google.com/

Show all 14 scopes  Show defaults only

## Use Gmail from your code

USE FROM CODE

Call Gmail from your application with a Keycard-issued token scoped to this resource.

After installing Gmail, your application exchanges a Keycard-issued access token for a token scoped to this resource. Pass the user’s access token as the `subject_token`.

- [Python](#tab-panel-114)
- [TypeScript](#tab-panel-115)

```
from keycardai.oauth import Client, BasicAuth, TokenType
import requests


# Exchange the user's Keycard token for a Gmail token.
with Client(
    "https://<zone-id>.keycard.cloud",
    auth=BasicAuth("<your-client-id>", "<your-client-secret>"),
) as client:
    response = client.exchange_token(
        subject_token=user_access_token,
        subject_token_type=TokenType.ACCESS_TOKEN,
        resource="https://gmail.googleapis.com",
    )


# Call Gmail directly with the exchanged token.
r = requests.get(
    "https://gmail.googleapis.com/<endpoint>",
    headers={"Authorization": f"Bearer {response.access_token}"},
)
```

```
import { TokenExchangeClient } from "@keycardai/oauth/tokenExchange";


const client = new TokenExchangeClient("https://<zone-id>.keycard.cloud", {
  clientId: "<your-client-id>",
  clientSecret: "<your-client-secret>",
});


const response = await client.exchangeToken({
  subjectToken: userAccessToken,
  resource: "https://gmail.googleapis.com",
});


// Call Gmail directly with the exchanged token.
const res = await fetch("https://gmail.googleapis.com/<endpoint>", {
  headers: { Authorization: `Bearer ${response.accessToken}` },
});
```

See the [OAuth SDK → Token Exchange](/sdk/oauth/#token-exchange/index.md) reference for the full client API.

## Setup

SETUP

Register your OAuth credentials with Keycard so the resource can issue tokens.

### Create a Google Cloud project

1. Go to the [Google Cloud Console](https://console.cloud.google.com)
2. Click **Select a project** → **New Project**
3. Enter a name and click **Create**

Note

If you’ve already created a Google Cloud project for another Google resource (Drive, Calendar), you can reuse the same project and OAuth credentials. Skip to [Enable the Gmail API](#enable-the-gmail-api).

### Configure the OAuth consent screen

1. Go to **APIs & Services** → **OAuth consent screen**
2. Select **External** user type (or Internal if using Google Workspace)
3. Fill in the app name, user support email, and developer contact
4. Add the Gmail scopes: `gmail.readonly`, `gmail.send`
5. Add test users if the app is in “Testing” status

Caution

Google apps in “Testing” status only allow access for explicitly listed test users. Add your own Google account as a test user, or publish the app for broader access.

### Create OAuth credentials

1. Go to **APIs & Services** → **Credentials**
2. Click **Create Credentials** → **OAuth client ID**
3. Select **Web application**
4. Under **Authorized JavaScript origins**, add `http://localhost:3000`
5. Add the Keycard-provided redirect URI under **Authorized redirect URIs**
6. Click **Create** and note the **Client ID** and **Client Secret**

### Enable the Gmail API

1. Navigate to **APIs & Services** → **Library**
2. Search for “Gmail API”
3. Click **Enable**

### Register in Keycard

1. Open [Keycard Console](https://console.keycard.ai) → your zone → **Resources**

2. Click **Explore Resources**

3. Find and click **Gmail** in the catalog

4. In the configuration dialog:

   - If this is your first Google resource, copy the **Redirect URL** and verify it’s added as an authorized redirect URI in your Google Cloud Console. Enter the **Client ID** and **Client Secret** from your OAuth credentials.
   - Review the **User scopes** - the defaults (`gmail.readonly`, `gmail.send`) are pre-populated

5. Click **Add Gmail API**

Tip

If you’ve already added another Google resource (Drive, Calendar), the dialog will show that the existing Google provider will be reused - no credentials needed. You’ll only need to review the scopes.

## Troubleshooting

TROUBLESHOOTING

Common errors when wiring Gmail into your zone.

Error 403: Access Not Configured

The Gmail API hasn’t been enabled in your Google Cloud project. Go to **APIs & Services** → **Library** and enable “Gmail API”.

Error 403: Insufficient Permission

The granted scopes don’t include the ones needed for the verification endpoint. Re-check:

- The scopes configured in your Keycard resource
- The scopes listed on the OAuth consent screen
- Whether the user granted all requested scopes during consent

Error: redirect\_uri\_mismatch

The redirect URI in Google Cloud Console doesn’t match what Keycard sends. Copy the exact redirect URI from Keycard Console and paste it into Google’s authorized redirect URIs.

## Related

RELATED

- [Catalog overview](/admin/catalog/index.md) - browse other API and MCP servers
- [Access policies](/admin/access-policies/index.md) - control who can use Gmail
- [Identity providers](/admin/identity-providers/index.md) - control who can sign in

[PreviousGitHub](/admin/catalog/api-servers/github/index.md)[NextGoogle Calendar](/admin/catalog/api-servers/google-calendar/index.md)