Skip to main content
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. Credentials saved for one Google app apply to all of them.

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

​
What you will set up

  • A Gmail connection through Google OAuth, in one click on OneCLI 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 OneCLI Cloud (one click)

1

Go to Connections

Open the OneCLI dashboard and navigate to Connections > 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.
OneCLI dashboard showing the Gmail connection page with per-action read and write permissions
On self-hosted OneCLI, or to use your own Google client on Cloud, see Use your own Google client.

​
Use your own Google client

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

1. Set up your Google client

Follow the Google setup guide. It enables the Google APIs, sets up the consent screen, creates the OAuth client, and adds the Redirect URI.You paste the client into Connections > Gmail > Custom credentials, under the Redirect URI the guide asks you to register:
OneCLI 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.

Custom credentials for Gmail in OneCLI.

Open Connections > Gmail, select Connect Gmail, pick your Google account, and click Allow.
OneCLI connect window for Gmail showing Configuration required and the Configure credentials button.

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: Write / delete actions: 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 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 add guardrails on top, like rate-limiting sends or requiring approval for emails matching a body condition. 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 guide to set up placeholder files that the gateway fills in at request time.

​
FAQ

Yes. Use the Read-only preset, or set Send email to Block or Ask so a person approves each send. See Per-action permissions.
No. The token stays in OneCLI, 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.
Open Connections > Gmail and connect again with the account you want. Agents with access use the new connection automatically.
Yes. Organization rules can rate-limit sends or require approval when the request body matches a condition.