Read, send, and manage Gmail from Guild agents

Integrations · Gmail

A Guild agent can read, triage, and send email from a Google account through the Gmail integration. Guild stores the OAuth token server-side, refreshes it automatically, and never exposes it to agent code or prompts. Credential policies and audit run through Guild’s credential proxy on every call.

Book a demo

See how teams govern agents that use Gmail.

Start free

Connect Gmail and scope your first agent.

What the Gmail integration exposes

The integration provides tools covering messages, threads, drafts, labels, mailbox history, attachments, account settings, filters, forwarding addresses, send-as aliases, and push notification watches. Tools follow the naming prefix gmail_oauth_ and can be imported as a full set or narrowed with pick. The tools table on this page reflects the latest published version of the package.

How it works

Open Credentials in Guild

Go to Credentials in Guild. The page lists services you can connect.

Authorize your Google account

Click Gmail and complete the OAuth authorization flow. Guild stores the token and refreshes it automatically.

Import tools into your agent

Import GmailOauthTools from the package and spread it into your agent’s tools object. Use pick to include only the tools your agent needs.

Why Gmail access needs governing

Gmail tools can send messages, delete threads permanently, modify filters, and update forwarding settings. Guild’s credential proxy sits between every agent call and the Gmail API: it checks credential policies before the request leaves Guild, then injects the OAuth token server-side. Agent code never sees the credential. You can write ALLOW and DENY rules that restrict which gmail_oauth_ operations an agent may call, and scope those rules to specific agents or workspaces on the same connected credential. Credentials can be scoped to an account, a single workspace, a member, or one agent. A workspace can be restricted to its own credentials so it never falls back to the organization’s shared token. These controls mean a triage agent that only reads mail and a sending agent that dispatches replies can share one Gmail connection without sharing each other’s permissions.

About the Gmail integration

The @guildai-services/guildlabs~gmail-oauth package gives your agents access to the Gmail API through Guild’s Gmail integration.

Authentication

Type: OAuth 2.0
Token management: Refreshed automatically

Setup

Open Credentials

Go to Credentials in Guild.

Connect Gmail

Click Gmail and authorize with your Google account.

Usage

import { GmailOauthTools } from "@guildai-services/guildlabs~gmail-oauth"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that reads and sends email",
  tools: { ...GmailOauthTools },
})

Selecting specific tools

Tools are named with the gmail_oauth_ prefix. Use pick() to include only what your agent needs.

import { GmailOauthTools } from "@guildai-services/guildlabs~gmail-oauth"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that monitors and replies to email",
  tools: {
    ...pick(GmailOauthTools, [
      "gmail_oauth_users_messages_list",
      "gmail_oauth_users_messages_get",
      "gmail_oauth_users_messages_send",
    ]),
  },
})

Tools

Tools in the latest published version of guildlabs~gmail-oauth:

All 59 tools

Tool	What it does
`gmail_oauth_users_drafts_create`	Body must be {“message”: {“raw”: ""}}. “raw” goes inside “message”, never at the top level, and do not build payload.body.data.
`gmail_oauth_users_drafts_delete`	Immediately and permanently deletes the specified draft.
`gmail_oauth_users_drafts_get`	Gets the specified draft.
`gmail_oauth_users_drafts_list`	Lists the drafts in the user’s mailbox.
`gmail_oauth_users_drafts_send`	Sends an existing draft.
`gmail_oauth_users_drafts_update`	Body must be {“message”: {“raw”: ""}}. “raw” goes inside “message”, never at the top level, and do not build payload.body.data.
`gmail_oauth_users_get_profile`	Gets the current user’s Gmail profile.
`gmail_oauth_users_history_list`	Lists the history of all changes to the given mailbox.
`gmail_oauth_users_labels_create`	Creates a new label.
`gmail_oauth_users_labels_delete`	Immediately and permanently deletes the specified label and removes it from any messages and threads that it is applied to.
`gmail_oauth_users_labels_get`	Gets the specified label.
`gmail_oauth_users_labels_list`	Lists all labels in the user’s mailbox.
`gmail_oauth_users_labels_patch`	Patch the specified label.
`gmail_oauth_users_labels_update`	Updates the specified label.
`gmail_oauth_users_messages_attachments_get`	Gets the specified message attachment.
`gmail_oauth_users_messages_batch_delete`	Deletes many messages by message ID.
`gmail_oauth_users_messages_batch_modify`	Modifies the labels on the specified messages.
`gmail_oauth_users_messages_delete`	Immediately and permanently deletes the specified message.
`gmail_oauth_users_messages_get`	Gets the specified message.
`gmail_oauth_users_messages_import`	Imports a message into only this user’s mailbox, with standard email delivery scanning and classification.
`gmail_oauth_users_messages_insert`	Directly inserts a message into only this user’s mailbox.
`gmail_oauth_users_messages_list`	Lists the messages in the user’s mailbox.
`gmail_oauth_users_messages_modify`	Modifies the labels on the specified message.
`gmail_oauth_users_messages_send`	Sends an email immediately.
`gmail_oauth_users_messages_trash`	Moves the specified message to the trash.
`gmail_oauth_users_messages_untrash`	Removes the specified message from the trash.
`gmail_oauth_users_settings_filters_create`	Creates a filter.
`gmail_oauth_users_settings_filters_delete`	Immediately and permanently deletes the specified filter.
`gmail_oauth_users_settings_filters_get`	Gets a filter.
`gmail_oauth_users_settings_filters_list`	Lists the message filters of a Gmail user.
`gmail_oauth_users_settings_forwarding_addresses_create`	Creates a forwarding address.
`gmail_oauth_users_settings_forwarding_addresses_delete`	Deletes the specified forwarding address.
`gmail_oauth_users_settings_forwarding_addresses_get`	Gets the specified forwarding address.
`gmail_oauth_users_settings_forwarding_addresses_list`	Lists the forwarding addresses for the specified account.
`gmail_oauth_users_settings_get_auto_forwarding`	Gets the auto-forwarding setting for the specified account.
`gmail_oauth_users_settings_get_imap`	Gets IMAP settings.
`gmail_oauth_users_settings_get_language`	Gets language settings.
`gmail_oauth_users_settings_get_pop`	Gets POP settings.
`gmail_oauth_users_settings_get_vacation`	Gets vacation responder settings.
`gmail_oauth_users_settings_send_as_create`	Creates a custom “from” send-as alias.
`gmail_oauth_users_settings_send_as_delete`	Deletes the specified send-as alias.
`gmail_oauth_users_settings_send_as_get`	Gets the specified send-as alias.
`gmail_oauth_users_settings_send_as_list`	Lists the send-as aliases for the specified account.
`gmail_oauth_users_settings_send_as_patch`	Patch the specified send-as alias.
`gmail_oauth_users_settings_send_as_update`	Updates a send-as alias.
`gmail_oauth_users_settings_send_as_verify`	Sends a verification email to the specified send-as alias address.
`gmail_oauth_users_settings_update_auto_forwarding`	Updates the auto-forwarding setting for the specified account.
`gmail_oauth_users_settings_update_imap`	Updates IMAP settings.
`gmail_oauth_users_settings_update_language`	Updates language settings.
`gmail_oauth_users_settings_update_pop`	Updates POP settings.
`gmail_oauth_users_settings_update_vacation`	Updates vacation responder settings.
`gmail_oauth_users_stop`	Stop receiving push notifications for the given user mailbox.
`gmail_oauth_users_threads_delete`	Immediately and permanently deletes the specified thread.
`gmail_oauth_users_threads_get`	Gets the specified thread.
`gmail_oauth_users_threads_list`	Lists the threads in the user’s mailbox.
`gmail_oauth_users_threads_modify`	Modifies the labels applied to the thread.
`gmail_oauth_users_threads_trash`	Moves the specified thread to the trash.
`gmail_oauth_users_threads_untrash`	Removes the specified thread from the trash.
`gmail_oauth_users_watch`	Set up or update a push notification watch on the given user mailbox.

Frequently asked questions

Can I limit my agent to reading email without letting it send?

Yes. Write a credential policy that DENY-lists gmail_oauth_users_messages_send and gmail_oauth_users_drafts_send, or use pick to include only read-oriented tools such as gmail_oauth_users_messages_list and gmail_oauth_users_messages_get when you define the agent.

Does Guild refresh the Gmail OAuth token automatically?

Yes. Token management is handled automatically by the integration; agent code does not need to request or store tokens.

Can the agent react to incoming email the moment it arrives?

Not yet via webhook events. The catalog entry for this integration lists no webhook events, so the agent cannot be triggered automatically by incoming mail. You can poll the mailbox using gmail_oauth_users_messages_list or use gmail_oauth_users_watch to set up a push notification watch on the mailbox.

Can one Gmail credential serve multiple workspaces with different permissions?

Yes. Connect one account-level credential and then write credential policy rules scoped to individual workspaces or agents. Each rule can allow or deny different gmail_oauth_ operations per workspace without requiring a separate Google account authorization.

Put a governed agent on Gmail this week

Book a demo

See how teams govern agents that use Gmail.

Start free

Connect Gmail and scope your first agent.

Also runs on Guild: Discord · Email · SendGrid · Slack Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Recruiting

Read, send, and manage Gmail from Guild agents

Book a demo

Start free

What the Gmail integration exposes

How it works

Why Gmail access needs governing

About the Gmail integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Frequently asked questions

Put a governed agent on Gmail this week

Book a demo

Start free

Book a demo

Start free

​What the Gmail integration exposes

​How it works

​Why Gmail access needs governing

​About the Gmail integration

​Authentication

​Setup

​Usage

​Selecting specific tools

​Tools

​Frequently asked questions

​Put a governed agent on Gmail this week

Book a demo

Start free

​Related

What the Gmail integration exposes

How it works

Why Gmail access needs governing

About the Gmail integration

Authentication

Setup

Usage

Selecting specific tools

Tools

Frequently asked questions

Put a governed agent on Gmail this week

Related