> For the complete documentation index, see [llms.txt](https://docs.eesel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eesel.ai/integrations/communication/gmail.md). # Gmail Connect one Gmail mailbox so your agent searches messages, reads threads, drafts or sends replies and manages labels, on your instructions or on a schedule. Invite your AI teammate into Gmail and it works the mailbox: it searches messages, reads threads, drafts or sends replies, and manages labels. You give it access to one Google account, and it works only that mailbox. You stay in control the whole way. Nothing runs until you create an automation. For each action you then choose: run on its own, ask you first, or stay off.
A Gmail thread where someone asks about the refund window on annual plans, and the agent replies in the thread after reading the refund policy and the annual plan terms

A Gmail thread where the agent replied after reading the refund policy.

Gmail is not self-serve yet. Message us in the in-app chat or email to have it turned on. It does not appear in your integrations list until then. ## Quick start {% stepper %} {% step %} ### Ask your agent to connect Gmail Open the chat in your dashboard and ask it to connect Gmail. It points you at your **Integrations** page and lists what it will do: search, read, send, draft and label email.
The dashboard chat where the user asks to connect Gmail and the agent replies with the Integrations page link and the list of what it can do once connected

The dashboard chat with the Integrations page link.

Open **Integrations > Gmail** in the left sidebar. **Connect** is in the top right.
The Gmail integration page before connecting, with a Connect button in the top right, an About section, a How it works list and the start of a What you can do list

The Gmail integration page before you connect.

{% endstep %} {% step %} ### Sign in with Google **Connect** opens a notice saying the connection runs through Pipedream, the service that brokers the sign-in. **Continue** hands you to Google's sign-in and consent screen. Pick the account you want your agent to work in, read the mail permissions, then accept. You can remove the connection at any time.
A modal on the Gmail integration page saying eesel AI uses Pipedream to connect your account, with the eesel, Pipedream and Gmail logos and a Continue button

The Pipedream notice, with Continue leading to Google's sign-in.

A person approves this in the browser. {% endstep %} {% step %} ### Confirm the connection Google sends you back, and the modal confirms the account is connected. **Continue** returns you to the integration page.
A modal confirming the Gmail account was connected successfully, with a Continue button and the Pipedream name underneath

The confirmation modal after Google sends you back.

**Check it worked.** The integration page header shows **Connected** with the account, and the left sidebar now lists Gmail. From a terminal, `eesel status` shows the integration as connected with its source counts. {% endstep %} {% step %} ### Check what it can read and do **Sources** is what it can read, and the mailbox is listed there with a switch. **Automations** is where you pick a trigger and say what to do each time it happens. **Actions** is what it can do and when it needs your approval, grouped as **Read** and **Write**. Read is set to **Auto** on connection, and Write needs approval.
The Gmail integration page after connecting, showing Connected with the account, a Sources section listing the mailbox, an Automations section suggesting a new email trigger, and Actions with the Read group on Auto and the Write group on Needs approval

The connected Gmail integration page, with sources, automations and the two action groups.

{% endstep %} {% step %} ### Create your first automation Connecting alone does not start your agent. It needs an automation first. Ask in the dashboard chat for the mail you want handled and what should happen. Your agent picks the trigger, writes the instructions, switches the automation on, and names any action still waiting on your approval. Your plain-language description becomes the automation's instructions, so it skips mail you did not describe. See [Automations](/automations-and-schedules/automations-and-schedules.md).
The dashboard chat where the user asks for an automatic reply on new mail, and the agent reports the trigger it chose, the mail it will skip, the reply it will send and the action still waiting on approval

The dashboard chat where the agent reports the trigger, the filter and the action.

The trigger event is fixed when the automation is created. So a new automation is required for each different trigger event. Removing an approval gate is an action of its own, so your agent posts an approval card instead of deciding it. The card names the action, what changes if you allow it, and its reason. **Approve** and **Deny** decide it. Some cards also offer **Always allow**, which sets the action to run on its own from then on.
An approval card in the dashboard chat asking to let the Gmail send email action run without approval, with the reason given and Approve and Deny buttons

The approval card for letting the send action run without approval.

Back on the integration page, the automation is listed with its switch on. The **Write** group now reads **Custom**. Open the group to see each action and its setting.
The Gmail integration page with the new email automation listed and switched on, and the Write action group expanded to Custom with the send action set to run on its own and the label, draft and signature actions set to ask first

The automation switched on, with the Write group expanded to Custom.

**Check it worked.** Your **Automations** page lists the automation, switched on. From a terminal, `eesel automations` lists the automation as on. {% endstep %} {% step %} ### Check automation work in Gmail Send the mailbox a test email from another address and open the thread in Gmail. The reply is in the thread, sent from the connected account, with any label your agent applied.
A Gmail thread where an incoming email got an automatic reply from the agent, followed by a second reply written after the sender's question

The automatic reply in the Gmail thread.

{% endstep %} {% step %} ### Work your inbox from Slack With [Slack](/integrations/communication/slack.md) connected, mention your teammate in a thread and ask what is new in the inbox. It lists the newest mail with sender, time and a line on each, then offers to open one, draft a reply or act on it.
A Slack thread where a teammate mentions eesel to check the newest emails, and the app lists five of them with sender, time and a summary line each

The newest mail listed in a Slack thread.

Ask it to reply to one and say what to write. It sends the reply from the connected account and confirms what it sent and to whom.
The same Slack thread where the teammate asks for a follow-up reply to the first email, and the app confirms it replied and what it said

The reply confirmed in the same Slack thread.

Open Gmail and the follow-up is in the original thread, from the address you connected.
The Gmail thread showing the follow-up email the agent sent from the connected account, below the earlier messages in the same thread

The follow-up email in the Gmail thread.

{% endstep %} {% endstepper %} {% hint style="info" %} **From Claude Code, Cursor or a terminal.** The same setup works as commands: `eesel login`, then `eesel integrations connect gmail_pipedream`, which prints the details that connection method needs, including the sign-in link for a person to open. The approval is a human step: print the link for a person, wait for the connection status to change, and do not retry the link. `eesel status` then shows the integration as connected with its source counts, `eesel automations` lists your automations, and `eesel chat` asks your agent a question. Turning an automation on and setting its instructions have no command, so use the dashboard chat for those. Trigger keys for this page are in the Triggers table below. Full command reference: [The eesel CLI](/apis-and-developer-resources/cli.md). Step-by-step: [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md). From a Model Context Protocol (MCP) client: [Claude Code and MCP clients](/apis-and-developer-resources/claude-code-and-mcp-clients.md). {% endhint %} ## Sources, triggers and actions ### Sources Gmail adds one source, listed on the integration page with a switch. | Source | What your agent reads | | --------- | ----------------------------------------------------------------------------------------------------------------- | | **Gmail** | The mailbox of the Google account you signed in with. It searches messages and reads whole threads while it works | Your agent can only see what that mailbox can see. Every other integration on your agent is a source too, so a Gmail reply can also draw on your help center, files and other integrations. See [Integrations](/integrations/overview.md). ### Triggers Triggers are the Gmail events an automation can run on. | Trigger | Fires when | Best for | Key | | ----------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------- | | **New email received** | A new email arrives in the connected inbox | Auto-replying and triage | `gmail_pipedream_new_email` | | **New email matching search** | A new inbound email matches a Gmail search query you set, like `label:support -from:me` | Scoping to one address or topic | `gmail_pipedream_new_email_matching_search` | | **New labeled email** | An email receives one of the Gmail labels you choose to watch | Queues a person curates: label it, and your agent picks it up | `gmail_pipedream_new_labeled_email` | New mail is delivered on Pipedream's polling interval. So a reply follows the email after a short delay. ### Actions The integration page groups actions as **Read** and **Write**, with ten read actions and twelve write actions. They come from Gmail through Pipedream, and your agent loads the current list each time it runs. These are the ones you will use most. | Group | Action | What it does | | --------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | **Read** | Find emails | Searches the mailbox with Gmail search syntax (`from:`, `subject:`, `has:attachment`, date ranges) | | | Get thread | Reads the full back-and-forth of an email thread | | | List labels | Lists the labels in the mailbox, so labeling actions target real ones | | **Write** | Send Email | Sends a new email, or replies on an existing thread, from the connected account | | | Create Draft | Saves an unsent draft, new or as a reply on a thread, for a person to review and send | | | Modify Labels | Adds and removes labels on one or more messages. In Gmail this one action covers archive, trash, star, and mark read or unread too | | | Create Label | Creates a new label, including nested ones like `Clients/Acme` | | | Archive email / Bulk archive emails | Archives one message, or many at once | | | Update Signature for Primary Email Address | Sets the signature on the connected address | | | Update Signature for Email in Organization | Sets the signature on another address in the same Google organization | On connection the Read group runs on its own and the Write group asks you first. Set a whole group at once, or open it and set each action. Your agent replies as the connected Google account. See [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md). ## Troubleshooting
Don't see Gmail in your integrations list? It is not self-serve. Message us in the in-app chat or email and we will turn it on for your workspace.
Automation not firing on new mail? Check your **Automations** page shows the automation switched on, and that the email arrived in the connected inbox. The triggers watch incoming mail, not messages you send. On the matching-search or labeled-email trigger, check the query or watched labels match the message. New mail is delivered on Pipedream's polling interval, so give it a moment. Every run appears on the **Activity** page.
Agent isn't running a Gmail action? Check the action is on for this agent, that your instructions tell it when to use the action, and that the connection is still signed in. An action set to ask you first has not failed. It is waiting for someone to decide it.
A reply came back with "Recipient address required"? That is Gmail refusing a reply with no recipient. The Gmail send and draft actions do not work the recipient out from the thread. Tell your agent to reply to the sender's address, and it will fill the field.
Connection issues? Google access can expire or be revoked. Disconnect Gmail and connect it again, completing every prompt in the Google sign-in.
## FAQ
How do I keep a person in the loop? Two ways, and you can use both. Turn on **Create Draft** instead of **Send Email**, so your agent writes drafts your team sends from Gmail. Or leave **Send Email** on ask you first, so it shows you what it wants to send and waits.
Does connecting Gmail start sending email on its own? No. Connecting only gives your agent access to the mailbox. It needs an automation before it acts at all, and the write actions ask you first until you change that.
Can I limit which emails my agent handles? Yes, at two levels. The **New email matching search** trigger scopes by a Gmail search query, and **New labeled email** only fires on the labels you watch. The automation's instructions then describe the mail you want in plain language, and what to do with it.
Can my agent delete email? It can move a message to the trash through the label actions, and it can archive mail. Both only exist on your agent if you turn them on, and you can leave them on ask you first.
Which account does it act as? The Google account you signed in with. Mail it sends comes from that address, and it can only see what that mailbox can see. Most teams connect a shared support address rather than a personal one.
What is Pipedream doing here? Pipedream brokers the connection to Google, so you sign in once and there are no keys to copy. The Gmail triggers and actions come from it too. You may see it named on Google's consent screen and in the security notice Google emails you afterwards.
How is this billed? Pay-as-you-go. An email conversation your agent handles is one task, and connecting Gmail carries no charge of its own. Chats you run yourself from the eesel dashboard are free. See [Pricing](/pricing/overview.md) for rates, the annual commitment, and Enterprise.
## Related pages * [Helpdesk](/use-cases/helpdesk.md) for the customer-facing job your agent takes on in the inbox * [Slack](/integrations/communication/slack.md) for working the mailbox from a Slack thread * [Actions and Approvals](/instructions-and-memory/actions-and-approvals.md) for setting each action to run on its own, ask you first, or stay off * [Integrations overview](/integrations/overview.md) for how sources, triggers and actions fit together * [Set up from Claude Code or the terminal](/getting-started/set-up-from-a-coding-agent.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.eesel.ai/integrations/communication/gmail.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.