> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Let AI Agents Search, Draft, and Send Gmail

> Connect Gmail so agents can search, read, and draft email, with sending behind approval. The gateway handles OAuth, so agents never see your tokens.

> [!WARNING]
>
> **Per-app Google setup is deprecated.** All Google apps now share one Google OAuth client and one Redirect URI. To use your own client, follow the [Google setup guide](/docs/integrations/google.md). Credentials saved for one Google app apply to all of them.

## Overview

Buckle connects AI agents to Gmail through Google's OAuth flow. Agents can search your inbox, read messages, draft and send emails, and manage labels. The gateway injects OAuth credentials into requests to the Gmail API automatically.

This is useful for agents that need to process incoming messages, send notifications, or automate email workflows on your behalf.

## What you will set up

* A Gmail connection through Google OAuth, in one click on Buckle Cloud or with your own Google client
* Automatic token injection on requests to the Gmail API
* Per-action permissions: allow, ask, or block each Gmail action per agent

## Connect on Buckle Cloud (one click)

**1. Open the app**

Open the Buckle dashboard and navigate to **Settings** > **Apps** > **Gmail**.

**2. Authorize**

Click **Connect Gmail**. You'll go straight to Google: pick your account, review the permissions, and click **Allow**. No Google Cloud setup needed.

![The Gmail page in Buckle Settings, with a connected account and the agents it is on for](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/gmail-connection.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=42ae405e4bbfb7565b91333804d9d024)

On self-hosted Buckle, or to use your own Google client on Cloud, see [Use your own Google client](#self-hosted).

## Use your own Google client

> [!NOTE]
>
> This is for self-hosted Buckle, and for Buckle Cloud when you choose **Custom credentials** instead of one-click. One Google client serves every Google app in Buckle, so you set it up once. If you already did it for another Google app, skip to step 2.

> [accordion] 1. Set up your Google client
>
> Follow the [Google setup guide](/docs/integrations/google.md). It enables the Google APIs, sets up the consent screen, creates the OAuth client, and adds the Redirect URI.
>
> You paste the client into **Settings** > **Apps** > **Gmail** > **Custom credentials**, under the Redirect URI the guide asks you to register:
>
> ![Buckle Custom credentials card for Gmail with the setup guide link, the Redirect URI and its copy button, and the Client ID and Client Secret fields.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/gmail/buckle-custom-credentials-gmail.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=ce9be6718244d8ed56075aa2ef789053)
>
> Custom credentials for Gmail in Buckle.

> [accordion] 2. Connect Gmail
>
> Open **Settings** > **Apps** > **Gmail**, select **Connect Gmail**, pick your Google account, and click **Allow**.
>
> ![Buckle connect window for Gmail showing Configuration required and the Configure credentials button.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/gmail/buckle-connect-gmail.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=03413d57876862748544a6b618f85a31)
>
> The Gmail connect window before a Google client is set up.

## What agents can do

* Search your inbox for messages matching a query (sender, subject, date range, labels)
* Read the full content of individual emails, including attachments
* Draft new emails with specified recipients, subject, and body
* Send emails on your behalf
* Reply to or forward existing messages
* Create, rename, and delete labels
* Move messages between labels (e.g., archive, mark as read, move to a folder)
* List and filter threads by label or search criteria
* Batch modify messages (mark as read, add/remove labels)

## Per-action permissions

The dashboard lets you control exactly what agents can do with Gmail. Each action can be set to **Allow** (green), **Ask** (yellow, requires human approval), or **Block** (red).

**Read-only actions:**

| Action | Description |
| - | - |
| Search email threads | Find threads matching a query (sender, subject, date, labels) |
| Read email thread | View a full conversation thread |
| Read email message | Read individual message content and attachments |
| List labels | Browse available Gmail labels and folders |

**Write / delete actions:**

| Action | Description |
| - | - |
| Send email | Send a new email on your behalf |
| Create draft | Draft an email without sending |
| Modify message | Change labels, mark as read/unread, archive |
| Trash message | Move a message to trash |

Use the **Read-only** preset to let agents search and read but never send, or **Block** all write actions and configure individually.

## Controlling access

Access is per agent: [grant](/docs/guides/agent-access.md) the Gmail connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — for example, allow `search_messages` but require approval for `send_email`. Organization [rules](/docs/guides/rules.md) add guardrails on top, like rate-limiting sends or requiring approval for emails matching a body [condition](/docs/guides/rules.md#conditions). Everything is checked before credential injection, so a blocked request never reaches Gmail.

## Using with MCP servers

If your agent uses an MCP server that needs Gmail credentials locally, see the [Gmail credential stubs](/docs/guides/credential-stubs/gmail.md) guide to set up placeholder files that the gateway fills in at request time.

## FAQ

> [accordion] Can an agent read Gmail without being able to send?
>
> Yes. Use the **Read-only** preset, or set **Send email** to **Block** or **Ask** so a person approves each send. See [Per-action permissions](#per-action-permissions).

> [accordion] Does the agent see my Gmail OAuth token?
>
> No. The token stays in Buckle, and the gateway adds it to Gmail API requests at the proxy. The agent makes plain HTTP calls and never holds the credential. See [How it works](/docs/how-it-works.md).

> [accordion] How do I reconnect Gmail or switch accounts?
>
> Open **Settings** > **Apps** > **Gmail** and connect again with the account you want. Agents with access use the new connection automatically.

> [accordion] Can I require approval for emails that match certain content?
>
> Yes. Organization [rules](/docs/guides/rules.md) can rate-limit sends or require approval when the request body matches a [condition](/docs/guides/rules.md#conditions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.