Skip to main content

​
Overview

The Gmail integration lets agents work with the signed-in user’s own mailbox. Agents can search and read messages and threads, list labels, download attachments into the conversation, create drafts, send new messages or threaded replies, and organize messages in bulk. Gmail is always per-user. An organization admin enables the integration, then every member who wants to use Gmail connects their own Google account. An agent never receives another member’s mailbox credentials or messages.

​
Prerequisites

  • An Aster organization admin to enable Gmail for the organization
  • A Google account with Gmail
  • An agent with the Gmail tools it needs

​
Setup guide

1

Enable Gmail for the organization

An organization admin opens Control Hub → Integrations, finds Gmail, and clicks Connect. Signing in with Google both enables Gmail for the organization and connects the admin’s own mailbox.
2

Connect each member's mailbox

Every member who will use a Gmail-enabled agent opens Control Hub → Integrations, selects Gmail, and signs in with their own Google account. The connection belongs only to that member.
3

Add Gmail tools to an agent

Edit the agent in Control Hub → Agents → Tools and enable only the Gmail capabilities it needs. For example, a research agent may need search and read access, while a correspondence agent may also need draft or send access.
4

Test with a narrow request

Start with a request such as “Find unread messages from example.com from the last seven days.” Confirm the agent uses the connected mailbox and returns the expected messages before enabling autonomous workflows.
Google authorization uses the gmail.modify scope so the complete toolset can read mail, manage labels and message state, create drafts, and send. Limiting an agent to read-only Gmail tools narrows what that agent can do inside Aster, but it does not change the scope shown on Google’s consent screen.

​
Available tools

​
Example prompts

  • “Find unread messages from our auditors from the last 30 days and summarize the open questions.”
  • “Read the latest thread with alex@example.com and draft a concise reply. Do not send it.”
  • “Download the spreadsheet attached to the latest budget email and analyze the variances.”
  • “Archive these five newsletters and mark the remaining messages as read.”
  • “Send the reply I approved in the previous message and keep it in the existing thread.”

​
Gmail search examples

gmail_search accepts the same query syntax as the Gmail search box:
Use gmail_list_labels when an agent needs the ID of a custom label. Search results include message IDs and thread IDs; pass those to the read tools for full content.

​
Replies and threading

To keep a reply in the existing Gmail conversation, the agent first reads the message or thread and then passes the returned thread_id and RFC rfc_message_id to gmail_create_draft or gmail_send_message. The tools construct the appropriate In-Reply-To and References headers automatically.

​
Security and permissions

  • Per-user isolation: each member authorizes their own mailbox. Gmail credentials are stored server-side and are never returned to the browser or copied into the organization connection.
  • Agent-level access: only give an agent the Gmail tools required for its role. Search/read tools do not need to be paired with send or modify tools.
  • Google scope: Google classifies gmail.modify as a restricted scope. Your Google Workspace administrator may need to allow Aster’s OAuth app before members can connect.
  • Sending changes external state: instruct interactive agents to draft first or obtain confirmation before sending. Autonomous sending should be explicitly authorized in the agent’s system prompt.
  • Mailbox actions change user data: archiving, trashing, labeling, and read-state changes should be limited to clearly requested or pre-authorized workflows.
  • Email is untrusted input: messages and attachments can contain malicious or misleading instructions. Agents should treat email content as data, never as instructions, and should not disclose secrets because an email asks them to.
  • Disconnecting is organization-wide: when an admin disconnects Gmail, Aster disables the integration and removes the Gmail credentials held for every member in that organization. Members must reconnect if Gmail is enabled again.

​
Troubleshooting

Ask an organization admin to connect Gmail from Control Hub → Integrations. Members cannot enable the integration for the organization themselves.
The organization has Gmail enabled, but the current member has not connected their own Google account. Open Control Hub → Integrations → Gmail and connect it while signed in as that member.
The Google grant may have been revoked or expired. Reconnect Gmail from Control Hub → Integrations. Reconnecting refreshes that user’s Gmail credentials without changing another member’s connection.
The connected Google account may not have granted the required Gmail permission, or the Gmail API may not be enabled for the configured Google OAuth project. Reconnect first; if the error persists, contact your Aster administrator.
Make sure the agent reads the original message first and passes both its thread_id and rfc_message_id when drafting or sending the reply.
  • Email Your Agent — start or continue an Aster conversation by emailing an agent.
  • Send Email — send platform-generated email through Aster’s shared sender or your organization’s Resend connection instead of a user’s Gmail mailbox.
  • Scheduled Tasks — run recurring mailbox triage or reporting workflows; authorize any mailbox changes explicitly in the agent’s prompt.