> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Gmail

## Overview

The Gmail integration gives agents tools for working with email and a **New Email** trigger that starts or continues an agent conversation when a message arrives in the connected inbox.

## Capabilities

| Capability                | Support                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Zero retention mode (ZRM) | Not supported                                                                                           |
| Attachments in triggers   | Images (PNG, JPEG, GIF, WebP) and PDF files on incoming email — see the inbound attachments notes below |
| Attachments in tools      | Not supported — tools operate on text only                                                              |

## Setup

#### Open the integrations page

In the ElevenLabs dashboard, go to **Agents** > **Integrations** and select **Gmail**.

#### Connect with Google

Choose the Google account whose mailbox the agent should use and approve the requested
permissions.

#### Configure a New Email trigger

Select the agent and delivery behavior, then save the trigger.

> **Note**
>
> A Google Workspace administrator may need to allow the ElevenLabs Gmail application under **Admin
> Console** > **Security** > **API controls** before users in the domain can connect.

## New Email trigger

The trigger watches new messages in the connected Gmail inbox. Each Gmail thread maps to a separate agent conversation, so later replies continue with the existing thread context.

### Delivery behavior

* **Draft reply** creates a draft to the latest inbound message's `Reply-To` address, or its `From` sender when `Reply-To` is absent.
* **Draft reply all** also copies external recipients from the latest inbound message's `To` and `Cc` headers.
* **Send automatically to sender** sends the agent response immediately as the connected mailbox. Automatic responses go only to the latest message's `From` address and ignore `Reply-To`, `To`, and `Cc` recipients.

Draft reply is the default.

Draft reply all removes the connected mailbox and duplicate addresses from the recipient list. It uses recipients from the latest inbound message rather than accumulating every participant who has appeared anywhere in the thread.

Draft replies are limited to the first 25 valid recipients. Primary reply recipients are kept before copied recipients, and additional or malformed addresses are omitted. Review draft recipients before sending because inbound routing headers are supplied by the email sender.

The integration does not reconstruct BCC recipients. Gmail does not reliably expose the original BCC list, and silently adding those recipients to an automated reply would be unsafe.

### Google Groups and shared inboxes

Mail relayed by a mailing list carries `List-Id` and `Precedence: list` headers and is ignored by default. Google Groups add the same headers, so a shared inbox such as `support@yourdomain.com` that is a group delivering to the connected mailbox would never reach the agent.

The **Google Groups mail** option controls this:

* **Ignore group mail** (default) keeps today's behavior: every list delivery is ignored.
* **Accept groups in the mailbox's domain** dispatches mail relayed by a Google Group whose posting address (`List-Post` or `Mailing-list`) is in the same domain as the connected mailbox. Mailing lists on other domains, `Precedence: bulk` or `junk` mail, and automatic responses stay ignored.

When group mail is accepted, replies never target the group's own address, so **Draft reply all** copies the other external participants without posting the response back into the group. If an accepted group rewrote `From` to itself (the author's domain enforces DMARC), the author in `X-Original-Sender` is treated as the sender for filters, reply recipients and the `integration__gmail_sender` variable. Messages that are not accepted group mail always keep their `From` sender. A message with no reply address other than the group itself is not dispatched.

Every Google Group in the domain qualifies, including internal announcement lists, so set the **Recipient** filter to the shared inbox's group address.

### Filtering

Optional filters limit which emails trigger the agent:

* **Sender** and **Recipient** accept either an exact email address or a domain. Recipient matching checks the `To` and `Cc` headers.
* **Subject contains** performs a case-insensitive text match.

When multiple filters are set, an email must match all of them. Filters apply to the latest eligible new email in a thread. Earlier non-matching messages can still be included as conversation context when a later email matches.

Sender filters match the email's `From` header. They organize trigger traffic but do not authenticate the sender, so do not use them as a security boundary for agents with sensitive tools.

### Thread history and human replies

The agent receives new inbound messages and manual replies sent from the connected mailbox as conversation context. Replies previously generated by the trigger are not added again when Gmail returns them in the thread.

Outbound replies include Gmail's thread ID and the standard `In-Reply-To` and `References` headers. This keeps both drafts and automatically sent responses in the existing Gmail thread.

### Message formatting

Agent responses are sent as multipart email:

* a plain-text part with Markdown formatting removed and link destinations written out;
* an HTML part rendered from Markdown.

Raw HTML in an agent response is escaped. Remote Markdown images are rendered as text instead of embedded images, preventing an agent response from adding tracking pixels or other remote image loads.

### Inbound attachments

The agent can inspect attached PNG, JPEG, GIF, and WebP images up to 10 MB and PDF files up to 20 MB. Named inline images, such as pasted screenshots, are also included. Attachments use the agent's file-input configuration and count toward its per-conversation file limit.

When file input is disabled, unavailable, or has reached its configured limit, the agent is told that the email included an attachment but does not receive the file contents. Attachment contents are not made available to zero-retention agents.

## Limitations

* An incoming forwarded email is processed like an ordinary message: the agent receives its text body and replies to the person who forwarded it. The trigger cannot forward its response to another recipient; use Gmail tools for that workflow.
* BCC recipients are not included in reply-all responses.
* Reply-all does not include addresses that appeared only in older messages.
* Only the first non-empty agent response in a trigger turn is delivered. Later responses from the same turn are ignored.
* File types other than the supported image formats and PDFs are ignored. Unnamed inline assets and remote images referenced by HTML are not downloaded.
* Attachments are available as inbound context only; they are not included in trigger replies.
* Messages identified as automatic responses, bulk mail, mailing-list mail, drafts, sent mail, spam, or trash are not dispatched to the agent. Mail from Google Groups in the mailbox's own domain is dispatched only when the **Google Groups mail** option is set to accept it.