# Gmail (/integrations/gmail)





{/* MANUAL-CONTENT-START:intro */}

Use [Gmail](https://mail.google.com/) to send or draft messages, read and search mail, and manage labels and read status. Gmail triggers can start a workflow when new mail arrives.

{/* MANUAL-CONTENT-END */}

## OAuth scopes [#oauth-scopes]

Sim requests these scopes when someone connects a Gmail account. For a self-hosted deployment, register your own app with the provider using the settings below. See [Integrations and OAuth](/platform/self-hosting/integrations-oauth) for setup.

| Setting | Value |
| - | - |
| Redirect URI | `<NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/google-email` |
| Environment variables | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |

| Scope | Description |
| - | - |
| `https://www.googleapis.com/auth/userinfo.email` | View email address |
| `https://www.googleapis.com/auth/userinfo.profile` | View basic profile info |
| `https://www.googleapis.com/auth/gmail.send` | Send emails |
| `https://www.googleapis.com/auth/gmail.modify` | Read, compose, send, and modify email messages |
| `https://www.googleapis.com/auth/gmail.labels` | View and manage email labels |

## Use the block [#usage-instructions]

Send or draft messages, read and search mail, and manage labels and read status. New-mail triggers can start workflows.

## Actions [#actions]

### Gmail Send [#gmail-send]

Send emails using Gmail.

<ReferenceDetails>
  #### Input [#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 [#output]

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

### Gmail Draft [#gmail-draft]

Draft emails using Gmail.

<ReferenceDetails>
  #### Input [#input-1]

  | 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 [#output-1]

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

### Gmail Edit Draft [#gmail-edit-draft]

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

<ReferenceDetails>
  #### Input [#input-2]

  | 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 [#output-2]

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

### Gmail Read [#gmail-read]

Read emails from Gmail.

<ReferenceDetails>
  #### Input [#input-3]

  | 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 [#output-3]

  | 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 |
</ReferenceDetails>

### Gmail Search [#gmail-search]

Search emails in Gmail.

<ReferenceDetails>
  #### Input [#input-4]

  | 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 [#output-4]

  | Parameter | Type | Description |
  | - | - | - |
  | `results` | json | Array of search results |
</ReferenceDetails>

### Gmail Move [#gmail-move]

Move emails between labels/folders in Gmail.

<ReferenceDetails>
  #### Input [#input-5]

  | 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 [#output-5]

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

### Gmail Mark as Read [#gmail-mark-as-read]

Mark a Gmail message as read.

<ReferenceDetails>
  #### Input [#input-6]

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

  #### Output [#output-6]

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

### Gmail Mark as Unread [#gmail-mark-as-unread]

Mark a Gmail message as unread.

<ReferenceDetails>
  #### Input [#input-7]

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

  #### Output [#output-7]

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

### Gmail Archive [#gmail-archive]

Archive a Gmail message (remove from inbox).

<ReferenceDetails>
  #### Input [#input-8]

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

  #### Output [#output-8]

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

### Gmail Unarchive [#gmail-unarchive]

Unarchive a Gmail message (move back to inbox).

<ReferenceDetails>
  #### Input [#input-9]

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

  #### Output [#output-9]

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

### Gmail Delete [#gmail-delete]

Delete a Gmail message (move to trash).

<ReferenceDetails>
  #### Input [#input-10]

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

  #### Output [#output-10]

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

### Gmail Add Label [#gmail-add-label]

Add label(s) to a Gmail message.

<ReferenceDetails>
  #### Input [#input-11]

  | 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 [#output-11]

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

### Gmail Remove Label [#gmail-remove-label]

Remove label(s) from a Gmail message.

<ReferenceDetails>
  #### Input [#input-12]

  | 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 [#output-12]

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

### Gmail List Labels [#gmail-list-labels]

List all labels in a Gmail account

<ReferenceDetails>
  #### Input [#input-13]

  | Parameter | Type | Required | Description |
  | - | - | - | - |

  #### Output [#output-13]

  | Parameter | Type | Description |
  | - | - | - |
  | `labels` | json | Array of label objects with id, name, type, and visibility settings |
</ReferenceDetails>

## Triggers [#triggers]

A trigger starts a workflow when a supported event occurs in this service.

These triggers poll for new data on a schedule.

### Gmail Email Trigger [#gmail-email-trigger]

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

#### Configuration [#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., "subject:invoice", "from:[boss@company.com](mailto:boss@company.com)", "has:attachment"). Leave empty to search all emails. |
| `markAsRead` | boolean | No | Automatically mark emails as read after processing |
| `includeAttachments` | boolean | No | Download and include email attachments in the trigger payload |

#### Output [#output-14]

| Parameter | Type | Description |
| - | - | - |
| `email` | object | |
| ↳ `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` | array | 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 |