> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail

> Send and manage Gmail messages, drafts, threads, and labels from inside an agent workflow.

Gmail actions let an agent work with a mailbox directly in a flow. An agent can send and reply to messages, manage drafts and threads, apply and remove labels, and pass the results to later steps.

## Supported actions

| Group       | Actions                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------ |
| **Message** | Send, Reply, Get, Get All, Delete, Mark As Read, Mark As Unread, Add Labels, Remove Labels |
| **Draft**   | Create, Get, Get All, Delete                                                               |
| **Thread**  | Reply, Get, Get All, Delete, Trash, Untrash, Add Labels, Remove Labels                     |
| **Label**   | Create, Get, Get All, Delete                                                               |

## Prerequisites

<AccordionGroup>
  <Accordion title="Create a Google OAuth credential" icon="key">
    Set up a Google OAuth credential by following the [Google Cloud Console OAuth setup guide](/integrations/oauth-setup/google-cloud-console), store it in [Credential Management](/admin-hub/account_settings/credential-management), then select it on every Gmail action. Gmail actions also support end user authentication, so a step can act on each user's own mailbox.
  </Accordion>
</AccordionGroup>

## How to use these actions

* **Map text inputs from earlier steps.** Inputs such as **To**, **Subject**, and **Body** accept a value mapped from a previous step. **Max Results** and the **Is HTML** and **Include Spam Trash** toggles take fixed values.
* **Recipient fields accept multiple addresses.** **To**, **Cc**, and **Bcc** accept multiple comma separated addresses.
* **List actions use Gmail search syntax.** The **Query** input on the Get All actions uses Gmail search syntax such as `is:unread` or `from:user@example.com`.
* **Labels are comma separated.** **Label IDs** is a comma separated list.
* **Send HTML bodies.** Set **Is HTML** on to send an HTML body.

## Actions

### Message

#### Gmail Message Send

Sends a new message.

| Input       | Required | Description                                                   |
| ----------- | -------- | ------------------------------------------------------------- |
| **To**      | Yes      | Recipient addresses, comma separated for multiple recipients. |
| **Subject** | Yes      | The subject line of the message.                              |
| **Body**    | Yes      | The body content of the message.                              |
| **Cc**      | No       | Carbon copy addresses, comma separated.                       |
| **Bcc**     | No       | Blind carbon copy addresses, comma separated.                 |
| **Is HTML** | No       | Toggle. Set on to send the body as HTML. Defaults to off.     |

#### Gmail Message Reply

Replies to an existing message.

| Input          | Required | Description                               |
| -------------- | -------- | ----------------------------------------- |
| **Message ID** | Yes      | The message to reply to.                  |
| **Body**       | Yes      | The reply content.                        |
| **Is HTML**    | No       | Toggle. Set on to send the reply as HTML. |

#### Gmail Message Get

Retrieves a message by ID.

| Input          | Required | Description              |
| -------------- | -------- | ------------------------ |
| **Message ID** | Yes      | The message to retrieve. |

#### Gmail Message Get All

Lists messages.

| Input                  | Required | Description                                                              |
| ---------------------- | -------- | ------------------------------------------------------------------------ |
| **Max Results**        | No       | Maximum number of messages to return, from 1 to 500. Defaults to 10.     |
| **Query**              | No       | A Gmail search query, such as `is:unread` or `from:user@example.com`.    |
| **Label IDs**          | No       | Comma separated list of labels to filter by.                             |
| **Include Spam Trash** | No       | Toggle. Set on to include messages from spam and trash. Defaults to off. |

#### Gmail Message Delete

Deletes a message.

| Input          | Required | Description            |
| -------------- | -------- | ---------------------- |
| **Message ID** | Yes      | The message to delete. |

#### Gmail Message Mark As Read

Marks a message as read.

| Input          | Required | Description                  |
| -------------- | -------- | ---------------------------- |
| **Message ID** | Yes      | The message to mark as read. |

#### Gmail Message Mark As Unread

Marks a message as unread.

| Input          | Required | Description                    |
| -------------- | -------- | ------------------------------ |
| **Message ID** | Yes      | The message to mark as unread. |

#### Gmail Message Add Labels

Adds labels to a message.

| Input          | Required | Description                    |
| -------------- | -------- | ------------------------------ |
| **Message ID** | Yes      | The message to update.         |
| **Label IDs**  | Yes      | Comma separated labels to add. |

#### Gmail Message Remove Labels

Removes labels from a message.

| Input          | Required | Description                       |
| -------------- | -------- | --------------------------------- |
| **Message ID** | Yes      | The message to update.            |
| **Label IDs**  | Yes      | Comma separated labels to remove. |

### Draft

#### Gmail Draft Create

Creates a draft message.

| Input       | Required | Description                                                   |
| ----------- | -------- | ------------------------------------------------------------- |
| **To**      | Yes      | Recipient addresses, comma separated for multiple recipients. |
| **Subject** | Yes      | The subject line of the draft.                                |
| **Body**    | Yes      | The body content of the draft.                                |
| **Cc**      | No       | Carbon copy addresses, comma separated.                       |
| **Bcc**     | No       | Blind carbon copy addresses, comma separated.                 |
| **Is HTML** | No       | Toggle. Set on to use an HTML body. Defaults to off.          |

#### Gmail Draft Get

Retrieves a draft by ID.

| Input        | Required | Description            |
| ------------ | -------- | ---------------------- |
| **Draft ID** | Yes      | The draft to retrieve. |

#### Gmail Draft Get All

Lists drafts.

| Input           | Required | Description                                                        |
| --------------- | -------- | ------------------------------------------------------------------ |
| **Max Results** | No       | Maximum number of drafts to return, from 1 to 500. Defaults to 10. |

#### Gmail Draft Delete

Deletes a draft.

| Input        | Required | Description          |
| ------------ | -------- | -------------------- |
| **Draft ID** | Yes      | The draft to delete. |

### Thread

#### Gmail Thread Reply

Replies to a thread.

| Input         | Required | Description                               |
| ------------- | -------- | ----------------------------------------- |
| **Thread ID** | Yes      | The thread to reply to.                   |
| **Body**      | Yes      | The reply content.                        |
| **Is HTML**   | No       | Toggle. Set on to send the reply as HTML. |

#### Gmail Thread Get

Retrieves a thread by ID.

| Input         | Required | Description             |
| ------------- | -------- | ----------------------- |
| **Thread ID** | Yes      | The thread to retrieve. |

#### Gmail Thread Get All

Lists threads.

| Input                  | Required | Description                                                             |
| ---------------------- | -------- | ----------------------------------------------------------------------- |
| **Max Results**        | No       | Maximum number of threads to return, from 1 to 500. Defaults to 10.     |
| **Query**              | No       | A Gmail search query, such as `is:unread` or `from:user@example.com`.   |
| **Label IDs**          | No       | Comma separated list of labels to filter by.                            |
| **Include Spam Trash** | No       | Toggle. Set on to include threads from spam and trash. Defaults to off. |

#### Gmail Thread Delete

Deletes a thread.

| Input         | Required | Description           |
| ------------- | -------- | --------------------- |
| **Thread ID** | Yes      | The thread to delete. |

#### Gmail Thread Trash

Moves a thread to trash.

| Input         | Required | Description                  |
| ------------- | -------- | ---------------------------- |
| **Thread ID** | Yes      | The thread to move to trash. |

#### Gmail Thread Untrash

Restores a thread from trash.

| Input         | Required | Description                       |
| ------------- | -------- | --------------------------------- |
| **Thread ID** | Yes      | The thread to restore from trash. |

#### Gmail Thread Add Labels

Adds labels to a thread.

| Input         | Required | Description                    |
| ------------- | -------- | ------------------------------ |
| **Thread ID** | Yes      | The thread to update.          |
| **Label IDs** | Yes      | Comma separated labels to add. |

#### Gmail Thread Remove Labels

Removes labels from a thread.

| Input         | Required | Description                       |
| ------------- | -------- | --------------------------------- |
| **Thread ID** | Yes      | The thread to update.             |
| **Label IDs** | Yes      | Comma separated labels to remove. |

### Label

#### Gmail Label Create

Creates a label.

| Input                       | Required | Description                                                                                         |
| --------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| **Name**                    | Yes      | The name of the label.                                                                              |
| **Label List Visibility**   | No       | Visibility of the label in the label list, one of `labelShow`, `labelShowIfUnread`, or `labelHide`. |
| **Message List Visibility** | No       | Visibility of messages with the label in the message list, one of `show` or `hide`.                 |

#### Gmail Label Get

Retrieves a label by ID.

| Input        | Required | Description            |
| ------------ | -------- | ---------------------- |
| **Label ID** | Yes      | The label to retrieve. |

#### Gmail Label Get All

Lists labels.

This action takes no inputs beyond the credential.

#### Gmail Label Delete

Deletes a label.

| Input        | Required | Description          |
| ------------ | -------- | -------------------- |
| **Label ID** | Yes      | The label to delete. |

## Example

An agent that triages unread mail and replies on behalf of the user:

<Steps>
  <Step title="Find unread messages">
    A **Gmail Message Get All** action sets **Query** to `is:unread` and **Max Results** to a fixed value so the flow reads only the latest unread messages.
  </Step>

  <Step title="Draft the reply">
    A model step reads the message body and writes a response, then a **Gmail Message Reply** action maps **Message ID** to the message from the previous step and **Body** to the generated reply.
  </Step>

  <Step title="Mark and file">
    A **Gmail Message Mark As Read** action clears the unread flag, and a **Gmail Message Add Labels** action applies a follow up label by passing its ID into **Label IDs**.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Message or thread not found" icon="circle-question">
    The **Message ID** or **Thread ID** does not exist in the connected mailbox. Confirm the ID with a Get All action and that the credential is for the correct account.
  </Accordion>

  <Accordion title="Label does not exist" icon="tag">
    A label passed to **Label IDs** must be an existing label ID, not a label name. Use **Gmail Label Get All** to look up label IDs first, or create the label with **Gmail Label Create**.
  </Accordion>

  <Accordion title="Authentication failed" icon="lock">
    The Google OAuth credential expired or was revoked. Reconnect the credential and confirm the required Gmail scopes were granted during consent.
  </Accordion>

  <Accordion title="HTML body renders as plain text" icon="code">
    Set **Is HTML** on when the **Body** contains HTML markup. With the toggle off, the body is sent as plain text.
  </Accordion>
</AccordionGroup>

For issues common to every vendor, see the [Actions overview](/building-and-deploying-agents/agent-basics/actions/overview#troubleshooting).