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

# Gmail Integration: Let Agents Read, Draft & Send Email

> Search, read, draft, and send emails through the Gmail API. The gateway handles OAuth and token refresh so agents just make HTTP calls.

## Overview

OneCLI 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.

## Setup

<Steps>
  <Step title="Go to Connections">
    Open the OneCLI dashboard and navigate to **Connections** > **Gmail**.
  </Step>

  <Step title="Authorize">
    Click **Connect Gmail**. You'll be redirected to Google to authorize OneCLI. Review the permissions and click **Allow**.

    <Frame>
      <img src="https://mintcdn.com/chartdbinc/7PEMo_l0oXWo2kux/images/integrations/gmail-connection.png?fit=max&auto=format&n=7PEMo_l0oXWo2kux&q=85&s=400005b446600fe9e6988b2504145fe2" alt="OneCLI dashboard showing the Gmail connection page with per-action read and write permissions" width="2000" height="1201" data-path="images/integrations/gmail-connection.png" />
    </Frame>
  </Step>
</Steps>

## 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 with rules

You can also use OneCLI's [rules engine](/guides/rules) to add further restrictions. For example, rate-limit send operations or require approval for emails to external domains. Rules are evaluated 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](/guides/credential-stubs/gmail) guide to set up placeholder files that the gateway fills in at request time.