Gmail

Use Gmail 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.

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

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

Actions

Gmail Send

Send emails using Gmail.

Inputs and outputs

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.

Inputs and outputs

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.

Inputs and outputs

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.

Inputs and outputs

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.

Inputs and outputs

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.

Inputs and outputs

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 as Read

Mark a Gmail message as read.

Inputs and outputs

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 as Unread

Mark a Gmail message as unread.

Inputs and outputs

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).

Inputs and outputs

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).

Inputs and outputs

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).

Inputs and outputs

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.

Inputs and outputs

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.

Inputs and outputs

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

Gmail List Labels

List all labels in a Gmail account

Inputs and outputs

Input

Parameter	Type	Required	Description

Output

Parameter	Type	Description
`labels`	json	Array of label objects with id, name, type, and visibility settings

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

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., "subject:invoice", "from: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

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