How do I send an email with an attachment?

Attachments are read from binary properties in your workflow, not from file paths you type in. Place a file-download or file-read node before the Gmail node, then reference that node's binary property name in the Attachments field. You can reference multiple binary properties in one entry by separating them with commas.

I enabled 'Download Attachments' but nothing is downloading — what am I missing?

Downloading attachments requires two settings to be active together: 'Download Attachments' must be on, and 'Simplify' must be turned off (set to false). The simplified output only includes headers and a snippet, so attachments are suppressed. Once you disable Simplify, the full message body and any attachment data will be available.

Why does 'Add Labels' fail even though I typed the label name correctly?

The Add Labels and Remove Labels operations expect Gmail's internal label IDs, not the human-readable names you see in the Gmail interface. To get the correct IDs, run a Label: Get Many operation first and read the ID values from its output, then pass those into the label operation.

What credentials does this node require, and do I need to renew them manually?

The node uses Gmail OAuth2 credentials (credential type: gmailOAuth2). OAuth2 tokens refresh automatically, so you connect your Google account once through BusyBot's credential setup and the node handles token renewal without manual intervention.

My workflow is hitting Gmail rate limits when processing a list of messages. How should I handle this?

Gmail enforces aggressive API rate limits, and fetching a message list with attachment downloads compounds the problem because each message triggers an additional API call. Keep the Max Concurrency setting low on any Gmail node that processes lists, and if you don't need all results, disable 'Return All' and set a specific limit instead.

Google Gmail

Send, receive, and manage Gmail messages with attachment support

Overview

Google Gmail tool provides complete email management: send messages with attachments, receive and download messages with attachments, reply to messages and threads with attachments, create and manage drafts with attachments, organize with labels, manage conversation threads. Supports OAuth2 authentication with automatic token refresh.

Category: Communication
Tool Name: google_gmail
Version: 1

Appearance: Icon: si-gmail | Color: #D44638

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	`Input`
Output	`Output`, `Error`

Credentials

This tool requires Gmail OAuth2 credentials. See the Credentials Guide for setup instructions.

The node also offers a service-account path: set Authentication to serviceAccount and fill in the Service Account Email and Private Key parameters instead of connecting an account.

Resources

Resource	Value
Message	`message`
Draft	`draft`
Label	`label`
Thread	`thread`

Operations

Operation	Value	Description
Send	`send`	Send a new email message (Message resource)
Reply	`reply`	Reply to an existing message (Message resource)
Get	`get`	Get a single message by ID (Message resource)
Get Many	`getAll`	Get many messages with filtering (Message resource)
Delete	`delete`	Permanently delete a message (Message resource)
Mark as Read	`markAsRead`	Mark a message as read (Message resource)
Mark as Unread	`markAsUnread`	Mark a message as unread (Message resource)
Add Labels	`addLabels`	Add labels to a message (Message resource)
Remove Labels	`removeLabels`	Remove labels from a message (Message resource)
Create	`create`	Create a new draft (Draft resource)
Get	`get`	Get a draft by ID (Draft resource)
Get Many	`getAll`	Get many drafts (Draft resource)
Delete	`delete`	Delete a draft (Draft resource)
Create	`create`	Create a new label (Label resource)
Get	`get`	Get a label by ID (Label resource)
Get Many	`getAll`	Get all labels (Label resource)
Delete	`delete`	Delete a label (Label resource)
Get	`get`	Get a thread with all its messages (Thread resource)
Get Many	`getAll`	Get many threads (Thread resource)
Delete	`delete`	Permanently delete a thread (Thread resource)
Reply	`reply`	Reply to a message in a thread (Thread resource)
Trash	`trash`	Move a thread to trash (Thread resource)
Untrash	`untrash`	Remove a thread from trash (Thread resource)
Add Labels	`addLabels`	Add labels to a thread (Thread resource)
Remove Labels	`removeLabels`	Remove labels from a thread (Thread resource)

Parameters

Message: Send

Parameter	Type	Required	Default	Description
To (`sendTo`)	`string`	Yes	—	Comma-separated recipient email addresses. Supports expressions like {{ $json.email }}.
Subject	`string`	Yes	—	Subject line of the email. Supports expressions.
Email Type (`emailType`)	`options`	Yes	`html`	Whether the body is plain text or HTML.
				Options: `text`, `html`
Message	`string`	Yes	—	Email body content (text or HTML based on emailType). Supports expressions.
Options	`collection`	No	`{}`	Optional send settings. Add only the ones you need.
— Attachments (`attachmentsUi`)	`fixedCollection`	No	`{}`	Files to attach, taken from the item’s binary data. Add one entry per property.
— — Binary Property (`property`)	`string`	No	`data`	Name of the binary property containing the attachment. Multiple properties can be separated by comma.
— CC (`ccList`)	`string`	No	—	Comma-separated CC email addresses.
— BCC (`bccList`)	`string`	No	—	Comma-separated BCC email addresses.
— Reply-To (`replyTo`)	`string`	No	—	Reply-To email address.
— Sender Name (`senderName`)	`string`	No	—	Display name shown in recipient inboxes.

Message: Reply

Parameter	Type	Required	Default	Description
Message ID (`messageId`)	`string`	Yes	—	The Gmail message ID to operate on. Supports expressions.
Email Type (`emailType`)	`options`	Yes	`html`	Whether the body is plain text or HTML.
				Options: `text`, `html`
Message	`string`	Yes	—	Email body content (text or HTML based on emailType). Supports expressions.
Options	`collection`	No	`{}`	Optional reply settings. Add only the ones you need.
— Attachments (`attachmentsUi`)	`fixedCollection`	No	`{}`	Files to attach, taken from the item’s binary data. Add one entry per property.
— — Binary Property (`property`)	`string`	No	`data`	Name of the binary property containing the attachment. Multiple properties can be separated by comma.
— CC (`ccList`)	`string`	No	—	Comma-separated CC email addresses.
— BCC (`bccList`)	`string`	No	—	Comma-separated BCC email addresses.
— Sender Name (`senderName`)	`string`	No	—	Display name shown in recipient inboxes.
— Reply to Sender Only (`replyToSenderOnly`)	`boolean`	No	`false`	Whether to reply to sender only instead of all recipients.
— Reply to Recipients Only (`replyToRecipientsOnly`)	`boolean`	No	`false`	Whether to exclude the sender from the reply.

Message: Get

Parameter	Type	Required	Default	Description
Message ID (`messageId`)	`string`	Yes	—	The Gmail message ID to operate on. Supports expressions.
Simplify (`simple`)	`boolean`	No	`true`	Whether to return simplified metadata or full parsed content.
Download Attachments (`downloadAttachments`)	`boolean`	No	`false`	Whether to download email attachments as binary data. Only applies when Simplify is false. (shown when Simplify is `false`)
Attachment Prefix (`attachmentPrefix`)	`string`	No	`attachment_`	Prefix for binary property names for downloaded attachments. An index starting at 0 is appended. (shown when Simplify is `false` and Download Attachments is `true`)

Message: Get Many

Parameter	Type	Required	Default	Description
Return All	`boolean`	No	`false`	Whether to return all results or only up to a given limit.
Limit	`number`	No	`50`	Max number of results to return. (shown when Return All is `false`)
Simplify (`simple`)	`boolean`	No	`true`	Whether to return simplified metadata or full parsed content.
Filters	`collection`	No	`{}`	Narrow the message list. Add only the filters you need.
— Search Query (`q`)	`string`	No	—	Gmail search query syntax.
— Label IDs (`labelIds`)	`string`	No	—	Comma-separated label IDs to filter by.
— Include Spam and Trash (`includeSpamTrash`)	`boolean`	No	`false`	Whether spam and trash are searched too.
— Read Status (`readStatus`)	`options`	No	`unread`	Which messages to include by read state.
				Options: `both` (Unread and Read), `unread` (Unread Only), `read` (Read Only)
— Sender	`string`	No	—	Filter by sender email or name.
— Received After (`receivedAfter`)	`string`	No	—	ISO date string or Unix timestamp. Only return emails received after this time.
— Received Before (`receivedBefore`)	`string`	No	—	ISO date string or Unix timestamp. Only return emails received before this time.
Download Options (`downloadOptions`)	`collection`	No	`{}`	Attachment handling for the fetched messages. (shown when Simplify is `false`)
— Download Attachments (`downloadAttachments`)	`boolean`	No	`false`	Whether to download email attachments as binary data.
— Attachment Prefix (`attachmentPrefix`)	`string`	No	`attachment_`	Prefix for binary property names.

Message: Delete

Parameter	Type	Required	Default	Description
Message ID (`messageId`)	`string`	Yes	—	The Gmail message ID to operate on. Supports expressions.

Message: Mark as Read

Parameter	Type	Required	Default	Description
Message ID (`messageId`)	`string`	Yes	—	The Gmail message ID to operate on. Supports expressions.

Message: Mark as Unread

Parameter	Type	Required	Default	Description
Message ID (`messageId`)	`string`	Yes	—	The Gmail message ID to operate on. Supports expressions.

Message: Add Labels

Parameter	Type	Required	Default	Description
Message ID (`messageId`)	`string`	Yes	—	The Gmail message ID to operate on. Supports expressions.
Label IDs (`labelIds`)	`string`	Yes	—	Comma-separated label IDs to add or remove. You can find label IDs via the label:getAll operation.

Message: Remove Labels

Parameter	Type	Required	Default	Description
Message ID (`messageId`)	`string`	Yes	—	The Gmail message ID to operate on. Supports expressions.
Label IDs (`labelIds`)	`string`	Yes	—	Comma-separated label IDs to add or remove. You can find label IDs via the label:getAll operation.

Draft: Create

Parameter	Type	Required	Default	Description
Subject	`string`	Yes	—	Subject line of the draft. Supports expressions.
Email Type (`emailType`)	`options`	Yes	`text`	Whether the body is plain text or HTML.
				Options: `text`, `html`
Message	`string`	Yes	—	Draft body content. Supports expressions.
Draft Options (`draftOptions`)	`collection`	No	`{}`	Optional draft settings. Add only the ones you need.
— Attachments (`attachmentsUi`)	`fixedCollection`	No	`{}`	Files to attach, taken from the item’s binary data. Add one entry per property.
— — Binary Property (`property`)	`string`	No	—	Name of the binary property containing the attachment.
— To (`sendTo`)	`string`	No	—	Comma-separated recipient email addresses.
— CC (`ccList`)	`string`	No	—	Comma-separated CC email addresses.
— BCC (`bccList`)	`string`	No	—	Comma-separated BCC email addresses.
— Reply-To (`replyTo`)	`string`	No	—	Reply-To email address.
— From Alias (`fromAlias`)	`string`	No	—	Gmail alias email to send from.
— Thread ID (`threadId`)	`string`	No	—	Thread ID to associate the draft with.

Draft: Get

Parameter	Type	Required	Default	Description
Draft ID (`draftId`)	`string`	Yes	—	The Gmail draft ID. Supports expressions.
Draft Get Options (`draftGetOptions`)	`collection`	No	`{}`	Attachment handling for the fetched draft.
— Download Attachments (`downloadAttachments`)	`boolean`	No	`false`	Whether to download draft attachments as binary data.
— Attachment Prefix (`attachmentPrefix`)	`string`	No	`attachment_`	Prefix for binary property names.

Draft: Get Many

Parameter	Type	Required	Default	Description
Return All	`boolean`	No	`false`	Whether to return all results or only up to a given limit.
Limit	`number`	No	`50`	Max number of results to return. (shown when Return All is `false`)
Draft List Options (`draftListOptions`)	`collection`	No	`{}`	Listing and attachment settings.
— Include Spam and Trash (`includeSpamTrash`)	`boolean`	No	`false`	Whether spam and trash are included.
— Download Attachments (`downloadAttachments`)	`boolean`	No	`false`	Whether to download draft attachments as binary data.
— Attachment Prefix (`attachmentPrefix`)	`string`	No	`attachment_`	Prefix for binary property names.

Draft: Delete

Parameter	Type	Required	Default	Description
Draft ID (`draftId`)	`string`	Yes	—	The Gmail draft ID. Supports expressions.

Label: Create

Parameter	Type	Required	Default	Description
Label Name (`labelName`)	`string`	Yes	—	Name of the label to create. Supports expressions.
Label Options (`labelOptions`)	`collection`	No	`{}`	Visibility settings for the new label.
— Label List Visibility (`labelListVisibility`)	`options`	No	`labelShow`	Whether the label appears in the Gmail label list.
				Options: `labelHide` (Hide), `labelShow` (Show), `labelShowIfUnread` (Show If Unread)
— Message List Visibility (`messageListVisibility`)	`options`	No	`show`	Whether the label appears on messages in the message list.
				Options: `hide`, `show`

Label: Get

Parameter	Type	Required	Default	Description
Label ID (`labelId`)	`string`	Yes	—	The Gmail label ID. Supports expressions.

Label: Get Many

Parameter	Type	Required	Default	Description
Return All	`boolean`	No	`false`	Whether to return all results or only up to a given limit.
Limit	`number`	No	`50`	Max number of results to return. (shown when Return All is `false`)

Label: Delete

Parameter	Type	Required	Default	Description
Label ID (`labelId`)	`string`	Yes	—	The Gmail label ID. Supports expressions.

Thread: Get

Parameter	Type	Required	Default	Description
Thread ID (`threadId`)	`string`	Yes	—	The Gmail thread ID. Supports expressions.
Simplify (`simple`)	`boolean`	No	`true`	Whether to return simplified metadata or full parsed content.
Thread Get Options (`threadGetOptions`)	`collection`	No	`{}`	How much of the thread to return.
— Return Only Messages (`returnOnlyMessages`)	`boolean`	No	`true`	Whether to return only thread messages instead of the full thread object.

Thread: Get Many

Parameter	Type	Required	Default	Description
Return All	`boolean`	No	`false`	Whether to return all results or only up to a given limit.
Limit	`number`	No	`50`	Max number of results to return. (shown when Return All is `false`)
Thread Filters (`threadFilters`)	`collection`	No	`{}`	Narrow the thread list. Add only the filters you need.
— Search Query (`q`)	`string`	No	—	Gmail search query syntax.
— Label IDs (`labelIds`)	`string`	No	—	Comma-separated label IDs to filter by.
— Include Spam and Trash (`includeSpamTrash`)	`boolean`	No	`false`	Whether spam and trash are searched too.
— Read Status (`readStatus`)	`options`	No	`unread`	Which threads to include by read state.
				Options: `both` (Unread and Read), `unread` (Unread Only), `read` (Read Only)
— Received After (`receivedAfter`)	`string`	No	—	ISO date string or Unix timestamp.
— Received Before (`receivedBefore`)	`string`	No	—	ISO date string or Unix timestamp.

Thread: Reply

Parameter	Type	Required	Default	Description
Thread ID (`threadId`)	`string`	Yes	—	The Gmail thread ID. Supports expressions.
Message ID (`threadMessageId`)	`string`	Yes	—	The specific message in the thread to reply to. Supports expressions.
Email Type (`emailType`)	`options`	Yes	`text`	Whether the body is plain text or HTML.
				Options: `text`, `html`
Message	`string`	Yes	—	Reply body content. Supports expressions.
Thread Reply Options (`threadReplyOptions`)	`collection`	No	`{}`	Optional reply settings. Add only the ones you need.
— Attachments (`attachmentsUi`)	`fixedCollection`	No	`{}`	Files to attach, taken from the item’s binary data. Add one entry per property.
— — Binary Property (`property`)	`string`	No	—	Name of the binary property containing the attachment.
— CC (`ccList`)	`string`	No	—	Comma-separated CC email addresses.
— BCC (`bccList`)	`string`	No	—	Comma-separated BCC email addresses.
— Sender Name (`senderName`)	`string`	No	—	Display name shown in recipient inboxes.
— Reply to Sender Only (`replyToSenderOnly`)	`boolean`	No	`false`	Whether to reply to sender only instead of all recipients.
— Reply to Recipients Only (`replyToRecipientsOnly`)	`boolean`	No	`false`	Whether to exclude the sender from the reply.

Thread: Delete

Parameter	Type	Required	Default	Description
Thread ID (`threadId`)	`string`	Yes	—	The Gmail thread ID. Supports expressions.

Thread: Trash

Parameter	Type	Required	Default	Description
Thread ID (`threadId`)	`string`	Yes	—	The Gmail thread ID. Supports expressions.

Thread: Untrash

Parameter	Type	Required	Default	Description
Thread ID (`threadId`)	`string`	Yes	—	The Gmail thread ID. Supports expressions.

Thread: Add Labels

Parameter	Type	Required	Default	Description
Thread ID (`threadId`)	`string`	Yes	—	The Gmail thread ID. Supports expressions.
Label IDs (`threadLabelIds`)	`string`	Yes	—	Comma-separated label IDs.

Thread: Remove Labels

Parameter	Type	Required	Default	Description
Thread ID (`threadId`)	`string`	Yes	—	The Gmail thread ID. Supports expressions.
Label IDs (`threadLabelIds`)	`string`	Yes	—	Comma-separated label IDs.

All Operations

Parameter	Type	Required	Default	Description
Authentication	`options`	No	`oAuth2`	Authentication method to use.
				Options: `oAuth2`, `serviceAccount`
Google Account (`credentialId`)	`credential`	No	—	Connect or select your Google account. (shown when Authentication is `oAuth2`)
Service Account Email (`serviceAccountEmail`)	`string`	Yes	—	The email address of the Google service account. (shown when Authentication is `serviceAccount`)
Private Key (`serviceAccountPrivateKey`)	`string`	Yes	—	The private key from the service account JSON key file. (shown when Authentication is `serviceAccount`)
Max Concurrency	`number`	No	`5`	Maximum number of items to process concurrently. Lower values help avoid Gmail API rate limits.

Output Data

The Gmail response is merged into the incoming item JSON at the top level, so the fields you sent in pass through. Binary data from the input item is forwarded, and downloaded attachments are merged into it.

Operation	Output items
`message` / `send`, `reply`, `markAsRead`, `markAsUnread`, `addLabels`, `removeLabels`	One item — Gmail’s response for the message, including its `id` and `threadId`.
`message` / `get`	One item. With Simplify on, a flattened record: `id`, `threadId`, `snippet`, `sizeEstimate`, `historyId`, `labelIds`, plus every RFC header (`From`, `To`, `Subject`, `Date`, …) as a top-level field. With Simplify off, the fully parsed message, and — when Download Attachments is on — each attachment as a binary property named with the Attachment Prefix plus an index starting at 0.
`message` / `getAll`	Fans out — one output item per message, each shaped by Simplify exactly as for Get. Attachments are downloaded per message when Download Options turns them on.
`message` / `delete`	One item carrying `success: true` and `deletedMessageId`.
`draft` / `create`	One item — the created draft. `id` is the draft ID and `messageId` is the underlying message.
`draft` / `get`	One item — the draft, with attachments as binary properties when Download Attachments is on.
`draft` / `getAll`	Fans out — one output item per draft.
`draft` / `delete`	One item carrying `success: true` and `deletedDraftId`.
`label` / `create`, `get`	One item — the label record.
`label` / `getAll`	Fans out — one output item per label. Use this to find the label IDs the Add Labels / Remove Labels operations need.
`label` / `delete`	One item carrying `success: true` and `deletedLabelId`.
`thread` / `get`	With Return Only Messages on (the default), fans out one item per message in the thread; with it off, one item for the whole thread object.
`thread` / `getAll`	Fans out — one output item per thread.
`thread` / `reply`, `trash`, `untrash`, `addLabels`, `removeLabels`	One item — Gmail’s response for the thread.
`thread` / `delete`	One item carrying `success: true` and `deletedThreadId`.

Usage Examples

Send an email with a PDF attachment
Download all unread emails with attachments
Reply to a message in a thread
Create a draft email with CC and BCC
Search for emails from a specific sender
Add labels to organize emails
Get all messages in a thread

Example Configuration

Send an HTML email with an attachment, CC and BCC:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "message",
    "operation": "send",
    "sendTo": "recipient@example.com",
    "subject": "HTML Email with Attachments",
    "emailType": "html",
    "message": "<h1>Hello</h1><p>This is an HTML email.</p>",
    "options": {
      "ccList": "cc@example.com,cc2@example.com",
      "bccList": "bcc@example.com",
      "senderName": "John Doe",
      "replyTo": "noreply@example.com",
      "attachmentsUi": {
        "attachmentsBinary": [
          { "property": "data" }
        ]
      }
    }
  }
}

Reply to the sender only:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "message",
    "operation": "reply",
    "messageId": "{{ $json.id }}",
    "emailType": "text",
    "message": "Thank you for your email.",
    "options": {
      "replyToSenderOnly": true
    }
  }
}

Search for messages:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "message",
    "operation": "getAll",
    "returnAll": false,
    "limit": 50,
    "simple": true,
    "filters": {
      "q": "is:unread",
      "sender": "important@example.com",
      "receivedAfter": "2024-01-01",
      "includeSpamTrash": false
    }
  }
}

Fetch a full message and download its attachments:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "message",
    "operation": "get",
    "messageId": "abc123def456",
    "simple": false,
    "downloadAttachments": true,
    "attachmentPrefix": "attachment_"
  }
}

Create a draft:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "draft",
    "operation": "create",
    "subject": "Draft Email",
    "emailType": "html",
    "message": "<p>This is a draft email.</p>",
    "draftOptions": {
      "sendTo": "recipient@example.com",
      "ccList": "cc@example.com",
      "replyTo": "reply@example.com"
    }
  }
}

Add labels to a message:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "message",
    "operation": "addLabels",
    "messageId": "abc123def456",
    "labelIds": "Label_1,Label_2"
  }
}

Create a label:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "label",
    "operation": "create",
    "labelName": "Important Projects",
    "labelOptions": {
      "labelListVisibility": "labelShow",
      "messageListVisibility": "show"
    }
  }
}

Reply inside a thread:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "thread",
    "operation": "reply",
    "threadId": "thread123",
    "threadMessageId": "msg456",
    "emailType": "text",
    "message": "Thanks for the thread discussion.",
    "threadReplyOptions": {
      "replyToRecipientsOnly": false,
      "ccList": "team@example.com"
    }
  }
}

Get a thread as individual messages:

{
  "type": "google_gmail",
  "parameters": {
    "resource": "thread",
    "operation": "get",
    "threadId": "thread123",
    "simple": false,
    "threadGetOptions": {
      "returnOnlyMessages": true
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Full Gmail integration for sending, receiving, replying to emails, managing drafts/labels/threads with attachment support via Google API.

Parameter Dependencies

Key relationships to remember:

downloadAttachments requires simple: false
attachmentPrefix requires downloadAttachments: true
limit requires returnAll: false
Collection parameters like options, filters use flat object structure
Each resource type has different available operations
Reply operations can target either messages or threads

Notes

Attachments come from binary properties, not file paths. Put a download or read node upstream, then name its binary property in the Attachments entry. One entry can name several properties separated by commas.
Simplify hides the body. The simplified shape carries headers and a snippet only; turn it off when you need the full text or the attachments.
Label IDs, not label names. Add Labels and Remove Labels take Gmail’s internal IDs — run Label: Get Many first and read them from its output.
Keep Max Concurrency low. Gmail rate-limits aggressively, and a message list with attachment downloads makes one API call per message.