> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Gmail
> Connect Gmail so agents can search, read, draft, send, organize, and download attachments from each user's mailbox
## 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
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.
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.
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.
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
| Tool | What it does |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `gmail_search` | Searches or lists messages with Gmail search syntax, label filters, pagination, and optional Spam/Trash inclusion. Returns up to 50 messages per call. |
| `gmail_read_message` | Reads one message's headers, decoded text or HTML body, labels, reply identifiers, and attachment metadata. |
| `gmail_read_thread` | Reads up to 50 messages from a conversation, oldest-first or newest-first. |
| `gmail_list_labels` | Lists system and custom labels with their IDs and available counts. |
| `gmail_download_attachment` | Downloads a message attachment into the conversation for analysis or use by another file-aware tool. |
| `gmail_create_draft` | Creates a new draft or a threaded reply without sending it. Supports plain text, HTML, CC, and BCC. |
| `gmail_send_message` | Sends a new message or threaded reply from the connected user's Gmail account. Supports plain text, HTML, CC, and BCC. |
| `gmail_modify_messages` | Applies an action to up to 100 messages: mark read/unread, archive, trash/untrash, star/unstar, or add/remove labels. |
## 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](mailto: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:
```text theme={null}
from:alice@example.com newer_than:30d
```
```text theme={null}
is:unread label:inbox has:attachment
```
```text theme={null}
subject:(quarterly report) after:2026/01/01 before:2026/04/01
```
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.
## Related
* [Email Your Agent](/features/email-your-agent) — start or continue an Aster conversation by emailing an agent.
* [Send Email](/tools/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](/features/scheduled-tasks) — run recurring mailbox triage or reporting workflows; authorize any mailbox changes explicitly in the agent's prompt.