---
title: Gmail
description: Send, read, search, and move Gmail messages or trigger workflows from Gmail events
---

import { BlockInfoCard } from "@/components/ui/block-info-card"

<BlockInfoCard 
  type="gmail_v2"
  color="#FFFFFF"
/>

{/* MANUAL-CONTENT-START:intro */}
[Gmail](https://mail.google.com/) is one of the world’s most popular email services, trusted by individuals and organizations to send, receive, and manage messages securely.

With the Gmail integration in Sim, you can:

- **Send emails**: Compose and send emails with support for recipients, CC, BCC, subject, body, and attachments
- **Create drafts**: Save email drafts for later review and sending
- **Read emails**: Retrieve email messages by ID with full content and metadata
- **Search emails**: Find emails using Gmail’s powerful search query syntax
- **Move emails**: Move messages between folders or labels
- **Manage read status**: Mark emails as read or unread
- **Archive and unarchive**: Archive messages to clean up your inbox or restore them
- **Delete emails**: Remove messages from your mailbox
- **Manage labels**: Add or remove labels from emails for organization

In Sim, the Gmail integration enables your agents to interact with your inbox programmatically as part of automated workflows. Agents can send notifications, search for specific emails, organize messages, and trigger actions based on email content—enabling intelligent email automation and communication workflows.
{/* MANUAL-CONTENT-END */}


## Usage Instructions

Integrate Gmail into the workflow. Can send, read, search, and move emails. Can be used in trigger mode to trigger a workflow when a new email is received.



## Actions

### `gmail_send`

Send emails using Gmail. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `to` | string | Yes | Recipient email address |
| `subject` | string | No | Email subject |
| `body` | string | Yes | Email body content |
| `contentType` | string | No | Content type for the email body \(text or html\) |
| `threadId` | string | No | Thread ID to reply to \(for threading\) |
| `replyToMessageId` | string | No | Gmail message ID to reply to - use the "id" field from Gmail Read results \(not the RFC "messageId"\) |
| `cc` | string | No | CC recipients \(comma-separated\) |
| `bcc` | string | No | BCC recipients \(comma-separated\) |
| `attachments` | file[] | No | Files to attach to the email |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Email labels |

### `gmail_draft`

Draft emails using Gmail. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `to` | string | Yes | Recipient email address |
| `subject` | string | No | Email subject |
| `body` | string | Yes | Email body content |
| `contentType` | string | No | Content type for the email body \(text or html\) |
| `threadId` | string | No | Thread ID to reply to \(for threading\) |
| `replyToMessageId` | string | No | Gmail message ID to reply to - use the "id" field from Gmail Read results \(not the RFC "messageId"\) |
| `cc` | string | No | CC recipients \(comma-separated\) |
| `bcc` | string | No | BCC recipients \(comma-separated\) |
| `attachments` | file[] | No | Files to attach to the email draft |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `draftId` | string | Draft ID |
| `messageId` | string | Gmail message ID for the draft |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Email labels |

### `gmail_edit_draft`

Update an existing Gmail draft in place without deleting and recreating it.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `draftId` | string | Yes | ID of the draft to update \(from Gmail List Drafts or Gmail Get Draft\) |
| `to` | string | Yes | Recipient email address |
| `subject` | string | No | Email subject |
| `body` | string | Yes | Email body content |
| `contentType` | string | No | Content type for the email body \(text or html\) |
| `threadId` | string | No | Thread ID to associate the draft with \(for threading\) |
| `replyToMessageId` | string | No | Gmail message ID to reply to - use the "id" field from Gmail Read results \(not the RFC "messageId"\) |
| `cc` | string | No | CC recipients \(comma-separated\) |
| `bcc` | string | No | BCC recipients \(comma-separated\) |
| `attachments` | file[] | No | Files to attach to the email draft |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `draftId` | string | Draft ID |
| `messageId` | string | Gmail message ID for the draft |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Email labels |

### `gmail_read`

Read emails from Gmail. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | No | Gmail message ID to read \(e.g., 18f1a2b3c4d5e6f7\) |
| `folder` | string | No | Folder/label to read emails from \(e.g., INBOX, SENT, DRAFT, TRASH, SPAM, or custom label name\) |
| `unreadOnly` | boolean | No | Set to true to only retrieve unread messages |
| `maxResults` | number | No | Maximum number of messages to retrieve \(default: 1, max: 10\) |
| `includeAttachments` | boolean | No | Set to true to download and include email attachments |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Email labels |
| `from` | string | Sender email address |
| `to` | string | Recipient email address |
| `subject` | string | Email subject |
| `date` | string | Email date |
| `body` | string | Email body text \(best-effort plain text\) |
| `hasAttachments` | boolean | Whether the email has attachments |
| `attachmentCount` | number | Number of attachments |
| `attachments` | file[] | Downloaded attachments \(if enabled\) |
| `results` | json | Summary results when reading multiple messages |

### `gmail_search`

Search emails in Gmail. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `query` | string | Yes | Search query for emails |
| `maxResults` | number | No | Maximum number of results to return \(e.g., 10, 25, 50\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `results` | json | Array of search results |

### `gmail_move`

Move emails between labels/folders in Gmail. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to move |
| `addLabelIds` | string | Yes | Comma-separated label IDs to add \(e.g., INBOX, Label_123\) |
| `removeLabelIds` | string | No | Comma-separated label IDs to remove \(e.g., INBOX, SPAM\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Email labels |

### `gmail_mark_read`

Mark a Gmail message as read. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to mark as read |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Updated email labels |

### `gmail_mark_unread`

Mark a Gmail message as unread. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to mark as unread |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Updated email labels |

### `gmail_archive`

Archive a Gmail message (remove from inbox). Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to archive |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Updated email labels |

### `gmail_unarchive`

Unarchive a Gmail message (move back to inbox). Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to unarchive |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Updated email labels |

### `gmail_delete`

Delete a Gmail message (move to trash). Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to delete |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Updated email labels |

### `gmail_add_label`

Add label(s) to a Gmail message. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to add labels to |
| `labelIds` | string | Yes | Comma-separated label IDs to add \(e.g., INBOX, Label_123\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Updated email labels |

### `gmail_remove_label`

Remove label(s) from a Gmail message. Returns API-aligned fields only.

#### Input

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `messageId` | string | Yes | ID of the message to remove labels from |
| `labelIds` | string | Yes | Comma-separated label IDs to remove \(e.g., INBOX, Label_123\) |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id` | string | Gmail message ID |
| `threadId` | string | Gmail thread ID |
| `labelIds` | array | Updated email labels |



## Triggers

A **Trigger** is a block that starts a workflow when an event happens in this service.

These run on a schedule \(**polling-based**\) — they check for new data rather than receiving push notifications.

### Gmail Email Trigger

Triggers when new emails are received in Gmail (requires Gmail credentials)

#### Configuration

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `triggerCredentials` | string | Yes | This trigger requires google email credentials to access your account. |
| `labelIds` | string | No | Choose which Gmail labels to monitor. Leave empty to monitor all emails. |
| `labelFilterBehavior` | string | Yes | Include only emails with selected labels, or exclude emails with selected labels |
| `searchQuery` | string | No | Optional Gmail search query to filter emails. Use the same format as Gmail search box \(e.g.,  |
| `markAsRead` | boolean | No | Automatically mark emails as read after processing |
| `includeAttachments` | boolean | No | Download and include email attachments in the trigger payload |

#### Output

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `email` | object | email output from the tool |
|   ↳ `id` | string | Gmail message ID |
|   ↳ `threadId` | string | Gmail thread ID |
|   ↳ `subject` | string | Email subject line |
|   ↳ `from` | string | Sender email address |
|   ↳ `to` | string | Recipient email address |
|   ↳ `cc` | string | CC recipients |
|   ↳ `date` | string | Email date in ISO format |
|   ↳ `bodyText` | string | Plain text email body |
|   ↳ `bodyHtml` | string | HTML email body |
|   ↳ `labels` | string | Email labels array |
|   ↳ `hasAttachments` | boolean | Whether email has attachments |
|   ↳ `attachments` | file[] | Array of email attachments as files \(if includeAttachments is enabled\) |
| `timestamp` | string | Event timestamp |

