Skip to main content

Gmail Component

Manage messages, labels, and drafts in Gmail.

Component key: google-gmail

Changelog ↓

Description​

Gmail is Google's email service for personal and business use. This component allows you to send, read, filter, and manage messages, labels, and drafts in Gmail accounts, as well as configure push notifications for real-time mailbox updates.

API Documentation​

This component was built using the Gmail API Documentation.

Documentation for the Node.js client used in this component can be found at https://googleapis.dev/nodejs/googleapis/latest/gmail/index.html

Most actions in this component have a Gmail User ID input. You can safely leave this input blank, and the default value, me will be used, indicating that the user who authenticated is the user whose Gmail account your integration will use.

Use labels to organize messages

Gmail uses labels in place of folders to organize messages. Messages in a user's inbox have a label of INBOX. You can apply custom labels to a message (so, you can loop only over messages with a particular label, etc).

Receiving notifications from Gmail​

Gmail supports push notifications to let you know when a mailbox changes (new message arrives, message is deleted, message is labeled, etc.).

This component provides two approaches for receiving Gmail push notifications:

Push Notifications​

For advanced use cases requiring manual control over the webhook lifecycle, use the Push Notifications trigger along with the manual setup actions:

  1. Create a Google Cloud IAM service account with the Pub/Sub Admin role in the same project as the Gmail OAuth app
  2. Create a Pub/Sub topic using the Create Topic action
  3. Create a Pub/Sub subscription using the Create Webhook Subscription action pointing to the trigger's webhook URL
  4. Create a Gmail watch request using the Create Push Notification action

For a complete example integration demonstrating manual push notification setup, see the Gmail with Webhooks example.

Connections​

Service Account​

The Service Account authentication method allows Gmail actions to run on behalf of Google Workspace users without requiring individual user authorization. This method is ideal for serve to server integrations and automated workflows.

When to Use Service Account

Service accounts are best suited for:

  • Server-to-server integrations within a Google Workspace organization
  • Automated workflows that need to access multiple users' Gmail accounts
  • Scenarios where individual user OAuth consent is not feasible

For customer facing integrations where each end user needs to authorize access, the OAuth 2.0 connection is recommended.

Prerequisites​

  • Google Cloud Platform (GCP) project with billing enabled
  • Google Workspace administrator access
  • Gmail API enabled in the GCP project

Setup Steps​

1. Create a Service Account

  1. Navigate to the Google Cloud Platform Console
  2. Go to IAM & Admin > Service Accounts
  3. Click Create Service Account
  4. Enter a name and description for the service account
  5. Click Create and Continue
  6. Click Done (no roles are required for Gmail API access)

2. Generate a Service Account Key

  1. Click on the newly created service account
  2. Navigate to the Keys tab
  3. Click Add Key > Create new key
  4. Select JSON as the key type
  5. Click Create
  6. A JSON file will be downloaded. This key contains sensitive data and should be stored securely
  7. Take note of the Client ID from the JSON file (required for domain wide delegation)

3. Enable Domain Wide Delegation

Service accounts require domain wide delegation to access Gmail data. Without this configuration, authentication will fail

  1. Login to the Google Workspace domain's Admin console and navigate to Main menu > Security > Access and data control > API Controls
  2. In the Domain wide delegation pane, select Manage Domain Wide Delegation
  3. Click Add new
  4. In the Client ID field, enter the service account's Client ID (found in the JSON key file)
  5. In the OAuth scopes (comma delimited) field, enter the scopes the application needs:
    • For full Gmail access: https://mail.google.com/
    • For read only access: https://www.googleapis.com/auth/gmail.readonly
    • For multiple scopes: https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/gmail.send
  6. Click Authorize

For more information on Gmail API scopes, refer to the Gmail API documentation.

Configure the Connection​

  1. Add a Gmail action to the integration that uses the Service Account connection
  2. In the Service Account Key File field, paste the entire contents of the JSON file downloaded in the setup steps
  3. In the User field, enter the email address of the Google Workspace user to impersonate (e.g., support@company.com)
  4. (Optional) In the Scopes field, specify custom scopes if needed. The default is https://mail.google.com/ which provides full Gmail API access
InputNotesExample
Service Account Key File

The JSON key file for the Google Service Account. Paste the entire contents of the downloaded JSON file including the BEGIN and END markers.

Scopes

Space-separated list of OAuth permission scopes. See <a href="https://developers.google.com/gmail/api/auth/scopes">Gmail API Scopes documentation</a> for available scopes.

https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send
User

The Google Workspace user email address to impersonate. This must be a valid user in the Workspace domain.

support@yourcompany.com

OAuth2​

The Gmail component authenticates requests through the Google Cloud Platform (GCP) OAuth 2.0 service.

To create a Gmail OAuth 2.0 app, a Google Developer account is required. Sign up at console.cloud.google.com.

Prerequisites​

  • Google Cloud Platform account with billing enabled
  • Access to create and configure GCP projects

Setup Steps​

  1. Open the Gmail API console
  2. Click ENABLE to enable the Gmail API for the project
  3. From the sidebar, select APIs & Services → Credentials
  4. Configure the OAuth consent screen:
    1. Click CONFIGURE CONSENT SCREEN
    2. Select External as the User Type (for customer-facing integrations)
    3. Fill in the required fields:
      • App name (company or product name)
      • Support email
      • App logo (optional but recommended)
      • Application domain
    4. Click Save and Continue
    5. On the Scopes page, add required scopes for the integration:
      • https://mail.google.com/ for full Gmail access, or
      • Specific scopes like https://www.googleapis.com/auth/gmail.readonly and https://www.googleapis.com/auth/gmail.send
    6. Click Save and Continue
    7. Add test users for testing purposes (required before publishing)
    8. Review the summary and click Back to Dashboard
  5. Create OAuth 2.0 credentials:
    1. Navigate to Credentials from the sidebar
    2. Click + CREATE CREDENTIALS → OAuth Client ID
    3. Select Web application as the Application type
    4. Under Authorized redirect URIs, add the OAuth callback URL: callback
    5. Click CREATE
  6. Copy the Client ID and Client Secret that are generated

Configure the Connection​

  • Enter the Client ID and Client Secret from the GCP Console
  • For Scopes, use one of the following configurations:
    • Full access (default): 
      https://mail.google.com/ https://www.googleapis.com/auth/pubsub
    • Limited access (example): 
      https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send https://www.googleapis.com/auth/pubsub
Pub/Sub Scope Requirement

The https://www.googleapis.com/auth/pubsub scope is required for push notification features. Include this scope if using the Push Notification Webhook trigger.

Publishing the OAuth App

The OAuth app will initially only work for test users added during setup. To allow all users to authenticate:

  1. Navigate to the OAuth consent screen in the GCP Console
  2. Click PUBLISH APP
  3. Follow Google's verification process if prompted (required for production use)

Without publishing, only test users will be able to authorize the integration.

InputNotesExample
Authorize URL

OAuth 2.0 authorization URL for Gmail authentication.

https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent
Client ID

The Client ID from the Google Cloud Console. Navigate to APIs & Services > Credentials to find this value.

123456789012-abc123def456ghi789jkl012mno345pqr.apps.googleusercontent.com
Client Secret

The Client Secret from the Google Cloud Console. Navigate to APIs & Services > Credentials to find this value.

Scopes

Space-separated list of OAuth permission scopes. See <a href="https://developers.google.com/gmail/api/auth/scopes">Gmail API Scopes documentation</a> for available scopes.

https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send
Token URL

OAuth 2.0 token URL for Gmail authentication.

https://oauth2.googleapis.com/token

Triggers​

New and Updated Emails​

Checks for new and updated email messages on a configured schedule. | key: pollChangesTrigger

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Get Message Details

When true, includes the message details in the response. <b>This will increase response time.</b>

false
Label ID

The label ID to filter history messages by.

INBOX
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

This trigger polls Gmail for mailbox changes on a scheduled basis using the Gmail History API.

For real-time notifications instead of scheduled polling, consider using the Push Notifications trigger with Gmail's push notification service.

The trigger checks for:

  • New messages: Messages added to the mailbox since the last poll
  • Deleted messages: Messages permanently deleted from the mailbox
  • Label changes: Labels added to or removed from messages (including read/unread, starred, categories, etc.)

How It Works​

  1. The trigger runs on the configured schedule (e.g., every 5 minutes)
  2. It queries Gmail's History API for changes since the last poll using a tracked historyId
  3. The History API returns records of all mailbox changes in chronological order
  4. The trigger updates its state with the latest historyId for the next poll
  5. If the historyId becomes invalid (typically after a week), the trigger automatically retrieves a new starting point

State Management​

Gmail uses history IDs to efficiently track mailbox changes. Each mailbox has a historyId that increments with every change. Instead of scanning all messages, this trigger:

  • Stores the last seen historyId between executions
  • Queries only for changes after that point
  • Handles expired history IDs automatically (Gmail may invalidate history IDs after ~7 days)

This approach is more efficient than polling all messages, as it only retrieves actual changes.

Configuration​

Configure the following inputs:

  • Connection: The Gmail OAuth connection to use
  • Gmail User ID (optional): The user ID or email address to monitor. Defaults to "me" (the authenticated user)
  • Label ID: Optional filter to receive changes only for messages with a specific label (e.g., "INBOX", "SENT", "UNREAD")
  • Get Message Details: When enabled, fetches full message content for each changed message. This significantly increases response time as it makes additional API calls for each message.

Returned Data​

The trigger returns a history response with four types of change records:

View example response
{
  "data": {
    "history": [
      {
        "id": "12345",
        "messagesAdded": [
          {
            "message": {
              "id": "18abc123def",
              "threadId": "18abc123xyz"
            }
          }
        ],
        "messagesDeleted": [
          {
            "message": {
              "id": "18def456ghi"
            }
          }
        ],
        "labelsAdded": [
          {
            "message": {
              "id": "18ghi789jkl",
              "labelIds": ["STARRED", "IMPORTANT"]
            }
          }
        ],
        "labelsRemoved": [
          {
            "message": {
              "id": "18jkl012mno",
              "labelIds": ["UNREAD"]
            }
          }
        ]
      }
    ],
    "historyId": "67890"
  }
}

By default, message objects only include id and threadId fields. Enable Get Message Details to include full message content (headers, body, attachments) for each changed message, though this increases execution time proportionally to the number of changed messages.

Push Notifications​

Receive and validate webhook requests from Gmail for manually configured Push Notification subscriptions. | key: pushNotificationWebhook

A Gmail push notification webhook can be configured to send information to a flow's webhook URL when mailbox changes occur (a new message arrives, a message is deleted, a message is labeled, etc.).

This trigger receives and validates webhook requests from Gmail for manually configured push notification subscriptions.

How Gmail Push Notifications Work​

Gmail push notifications use Google Cloud Pub/Sub to deliver real time updates when mailbox changes occur. Whenever a mailbox changes, the Gmail API publishes a notification to a configured Cloud Pub/Sub topic, which then pushes the notification to the webhook URL.

The notification payload includes:

  • The user's email address
  • A history ID indicating what changed
  • A timestamp of when the change occurred

This trigger automatically decodes the base64 encoded Pub/Sub payload data and makes it available in the message.decodedData field, so no additional decoding step is required.

Configuration Requirements​

To use this trigger, the following must be configured externally:

  1. Cloud Pub/Sub Topic: Create a Pub/Sub topic in a Google Cloud project with the Gmail API enabled
  2. IAM Permissions: Grant the Gmail API service account (gmail-api-push@system.gserviceaccount.com) permission to publish to the topic
  3. Cloud Pub/Sub Subscription: Create a push subscription pointing to this trigger's webhook URL
  4. Gmail Watch Request: Use the Create Push Notification (Watch Request) action to initiate a watch request for the desired user and topic

{
  "response": {
    "statusCode": 200,
    "contentType": "text/plain"
  },
  "payload": {
    "flow": {
      "id": "SW5zdGFuY2VGbG93Q29uZmlnOjEyMzQ1Njc4OTA==",
      "name": "Gmail Notifications Flow"
    },
    "startedAt": "2024-11-06T15:30:45.123Z",
    "integration": {
      "id": "SW50ZWdyYXRpb246OTg3NjU0MzIxMA==",
      "name": "Gmail Integration",
      "externalVersion": "1.0.0",
      "versionSequenceId": "SW50ZWdyYXRpb25WZXJzaW9uU2VxdWVuY2U6MTIzNDU2Nzg5MA=="
    },
    "headers": {
      "Accept": "application/json",
      "Accept-Encoding": "gzip, deflate, br",
      "Content-Type": "application/json",
      "From": "noreply@google.com",
      "Host": "hooks.example.com",
      "User-Agent": "APIs-Google; (+https://developers.google.com/webmasters/APIs-Google.html)",
      "X-Amz-Cf-Id": "xYzAbCdEfGhIjKlMnOpQrStUvW1234567890-Example-CloudFront-ID==",
      "X-Amzn-Trace-Id": "Root=1-65abc123-1234567890abcdef12345678"
    },
    "queryParameters": {},
    "rawBody": {
      "data": {},
      "contentType": "application/json"
    },
    "body": {
      "data": {
        "message": {
          "data": "eyJlbWFpbEFkZHJlc3MiOiJ1c2VyQGV4YW1wbGUuY29tIiwiaGlzdG9yeUlkIjoiMTIzNDU2Nzg5MCJ9",
          "decodedData": {
            "emailAddress": "user@example.com",
            "historyId": "1234567890"
          },
          "messageId": "1234567890123456",
          "message_id": "1234567890123456",
          "publishTime": "2024-11-06T15:30:45.123Z",
          "publish_time": "2024-11-06T15:30:45.123Z"
        },
        "subscription": "projects/example-project-123456/subscriptions/gmail-notifications-sub"
      },
      "contentType": "application/json"
    },
    "pathFragment": "",
    "webhookUrls": {
      "Gmail Notifications Flow": "https://hooks.example.com/trigger/aBcDeFgHiJkLmNoPqRsTuVwXyZ"
    },
    "webhookApiKeys": {
      "Gmail Notifications Flow": [
        "example_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890"
      ]
    },
    "invokeUrl": "https://hooks.example.com/trigger/aBcDeFgHiJkLmNoPqRsTuVwXyZ",
    "executionId": "SW5zdGFuY2VFeGVjdXRpb25SZXN1bHQ6OTg3NjU0MzIxMA==",
    "customer": {
      "id": "Q3VzdG9tZXI6MTIzNDU2Nzg5MA==",
      "name": "Acme Corporation",
      "externalId": "acme-corp-ext-12345"
    },
    "instance": {
      "id": "SW5zdGFuY2U6OTg3NjU0MzIxMA==",
      "name": "Gmail Integration - Acme Corp"
    },
    "user": {
      "id": "VXNlcjo5ODc2NTQzMjEw",
      "email": "admin@example.com",
      "name": "Admin User",
      "externalId": "admin-user-ext-67890"
    },
    "globalDebug": false
  }
}

Data Sources​

Select Label​

Select a label from the list of labels | key: selectLabel | type: picklist

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

Select Message​

Select a message from the list of messages | key: selectMessage | type: picklist

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Query String

Filter messages using Gmail search syntax. Supports the same query format as the Gmail search box.

from:user@example.com is:unread after:2024/01/01
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

Actions​

Create Push Notification (Watch Request)​

Enables the ability to send update notifications like new messages received. | key: createPushNotification

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Label ID

Gmail labels to filter notifications. System labels (INBOX, SENT, DRAFT, etc.) correspond to pre-defined elements in the Gmail interface.

["INBOX", "IMPORTANT"]
Topic Name

The full Pub/Sub topic name in the format: projects/{project-id}/topics/{topic-id}

projects/my-project-123456/topics/gmail-notifications
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "historyId": "9876543210",
    "expiration": "1731513045000"
  }
}

Delete Push Notification (Stop Mailbox Updates)​

Calls a stop notification. | key: deletePushNotification

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{}

Get Current User​

Get metadata about the authenticated user | key: getCurrentUser

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

{
  "data": {
    "emailAddress": "example@gmail.com",
    "historyId": "1234567",
    "messagesTotal": 12345,
    "threadsTotal": 12345
  }
}

Get Event History​

Fetch events that have occurred in the mailbox since the specified startHistoryId. | key: getEventHistory

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Fetch All

When true, fetches all pages of results using pagination.

false
History ID

The history ID to start retrieving history records from.

9876543210
Max Results

The maximum number of results to return per page.

100
Page Token

Page token from the previous response when looping through paginated history results.

09876543210abcdefg
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "history": [
      {
        "id": "9876543210",
        "messages": [
          {
            "id": "18c2f4b3e8a9d7f6",
            "threadId": "18c2f4b3e8a9d7f6"
          }
        ],
        "messagesAdded": [
          {
            "message": {
              "id": "18c2f4b3e8a9d7f6",
              "threadId": "18c2f4b3e8a9d7f6",
              "labelIds": [
                "INBOX",
                "UNREAD"
              ]
            }
          }
        ]
      },
      {
        "id": "9876543211",
        "messages": [
          {
            "id": "18c2f4b3e8a9d7f6",
            "threadId": "18c2f4b3e8a9d7f6"
          }
        ],
        "labelsAdded": [
          {
            "message": {
              "id": "18c2f4b3e8a9d7f6",
              "threadId": "18c2f4b3e8a9d7f6",
              "labelIds": [
                "INBOX",
                "UNREAD",
                "IMPORTANT"
              ]
            },
            "labelIds": [
              "IMPORTANT"
            ]
          }
        ]
      }
    ],
    "historyId": "9876543211",
    "nextPageToken": "12345678901234567890"
  }
}

Get Label by Name​

Get a label (including ID) by its name | key: getLabelByName

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Label Name
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "id": "Label_1234567890",
    "name": "Work Projects",
    "type": "user",
    "messageListVisibility": "show",
    "labelListVisibility": "labelShow",
    "color": {
      "backgroundColor": "#42d692",
      "textColor": "#ffffff"
    },
    "messagesTotal": 42,
    "messagesUnread": 5,
    "threadsTotal": 38,
    "threadsUnread": 4
  }
}

Get Message​

Get a message by ID | key: getMessageById

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Message ID

The unique identifier of the Gmail message.

18c1e2a4b5f6g7h8
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "id": "1234abcd",
    "threadId": "5678efgh",
    "labelIds": [
      "IMPORTANT",
      "SENT",
      "INBOX"
    ],
    "message": {
      "headers": {
        "mime-version": "1.0",
        "date": "2022-09-19T20:09:01.000Z",
        "message-id": "<Test-message-id@mail.gmail.com>",
        "subject": "Test Message",
        "from": {
          "value": [
            {
              "address": "example@gmail.com",
              "name": "Example Example"
            }
          ],
          "html": "<span class=\"mp_address_group\"><span class=\"mp_address_name\">Example Example</span> &lt;<a href=\"mailto:example@gmail.com\" class=\"mp_address_email\">example@gmail.com</a>&gt;</span>",
          "text": "Example Example <example@gmail.com>"
        },
        "to": {
          "value": [
            {
              "address": "example@gmail.com",
              "name": "Example Example"
            }
          ],
          "html": "<span class=\"mp_address_group\"><span class=\"mp_address_name\">Example Example</span> &lt;<a href=\"mailto:example@gmail.com\" class=\"mp_address_email\">example@gmail.com</a>&gt;</span>",
          "text": "Example Example <example@gmail.com>"
        },
        "content-type": {
          "value": "multipart/mixed",
          "params": {
            "boundary": "000000000000680fa005e90d488f"
          }
        }
      },
      "attachments": [],
      "text": "Example email body",
      "html": "<div dir=\"ltr\">Example email body<div><br></div></div>\n"
    }
  }
}

List Labels​

List all labels within this account | key: listLabels

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "labels": [
      {
        "id": "INBOX",
        "name": "INBOX",
        "type": "system",
        "messageListVisibility": "show",
        "labelListVisibility": "labelShow"
      },
      {
        "id": "SENT",
        "name": "SENT",
        "type": "system",
        "messageListVisibility": "show",
        "labelListVisibility": "labelShow"
      },
      {
        "id": "Label_1234567890",
        "name": "Work Projects",
        "type": "user",
        "messageListVisibility": "show",
        "labelListVisibility": "labelShow",
        "color": {
          "backgroundColor": "#42d692",
          "textColor": "#ffffff"
        },
        "messagesTotal": 42,
        "messagesUnread": 5,
        "threadsTotal": 38,
        "threadsUnread": 4
      }
    ]
  }
}

List Messages​

Get a list of messages | key: listMessages

InputNotesExample
Add Metadata

When true, includes additional metadata for each message. This will increase response time.

false
Connection

The Connection to use for Gmail Authorization.

Fetch All

When true, fetches all pages of results using pagination.

false
Labels

Filter messages by Gmail label IDs.

["INBOX", "UNREAD"]
Max Results

The maximum number of results to return per page.

100
Page Token

Page token from the previous response when looping through paginated results.

09876543210abcdefg
Query String

Filter messages using Gmail search syntax. Supports the same query format as the Gmail search box.

from:user@example.com is:unread after:2024/01/01
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "messages": [
      {
        "id": "abcd1234",
        "threadId": "efgh5678"
      }
    ]
  }
}

Raw Request​

Send raw HTTP request to Google Gmail | key: rawRequest

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Timeout

The maximum time that a client will await a response to its request

2000
URL

Input the path only (/v1/users/{userId}/messages), The base URL is already included (https://gmail.googleapis.com/gmail). For example, to connect to https://gmail.googleapis.com/gmail/v1/users/{userId}/messages, only /v1/users/{userId}/messages is entered in this field.

/v1/users/{userId}/messages
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

{
  "data": {
    "messages": [
      {
        "id": "18c2f4b3e8a9d7f6",
        "threadId": "18c2f4b3e8a9d7f6"
      },
      {
        "id": "18c2f4b3e8a9d7f5",
        "threadId": "18c2f4b3e8a9d7f5"
      }
    ],
    "nextPageToken": "12345678901234567890",
    "resultSizeEstimate": 2
  }
}

Send Message​

Send a new message | key: sendMessage

InputNotesExample
Attachments

Email attachments as key-value pairs. The key is the file name (e.g., 'document.pdf') and the value is the file data.

{ "report.pdf": "<file data>", "chart.png": "<image data>" }
BCC

Blind carbon copy (BCC) email addresses.

["bcc@example.com"]
CC

Carbon copy (CC) email addresses.

["cc@example.com"]
Connection

The Connection to use for Gmail Authorization.

Dynamic Attachments

An array of objects with 'key' and 'value' properties, where 'key' is the file name and 'value' is the binary file data. Typically used as a reference from a previous step. Ex. [{key: "my-attachment.pdf", value: <BINARY FILE DATA TO ATTACH>},{key: "another-attachment.xlsx", value: <BINARY EXCEL FILE DATA>}]

[{key: "my-attachment.pdf", value: <BINARY FILE DATA TO ATTACH>},{key: "another-attachment.xlsx", value: <BINARY EXCEL FILE DATA>}]
From

The sender email address or alias. This is the email address that will appear in the From field.

John Doe <john.doe@example.com>
HTML Body

HTML version of the email body. For email clients that support HTML.

<html><body><h1>Hello</h1><p>This is a reminder about our meeting tomorrow at 2 PM.</p></body></html>
Subject

The subject line of the email.

Meeting Reminder - Project Review
Plain Text Body

Plain text version of the email body. Used as fallback for email clients that do not support HTML.

Hello, This is a reminder about our meeting tomorrow at 2 PM. Best regards
To

Recipient email addresses.

["recipient@example.com"]
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "id": "18c2f4b3e8a9d7f6",
    "threadId": "18c2f4b3e8a9d7f6",
    "labelIds": [
      "SENT"
    ]
  }
}

Trash Message​

Send a message to the trash | key: trashMessageById

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Message ID

The unique identifier of the Gmail message.

18c1e2a4b5f6g7h8
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "id": "18c2f4b3e8a9d7f6",
    "threadId": "18c2f4b3e8a9d7f6",
    "labelIds": [
      "TRASH"
    ],
    "historyId": "9876543210",
    "internalDate": "1730913045000",
    "sizeEstimate": 2543,
    "snippet": "This is the beginning of the email message..."
  }
}

Untrash Message​

Remove a message from the trash | key: unTrashMessageById

InputNotesExample
Connection

The Connection to use for Gmail Authorization.

Message ID

The unique identifier of the Gmail message.

18c1e2a4b5f6g7h8
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "id": "18c2f4b3e8a9d7f6",
    "threadId": "18c2f4b3e8a9d7f6",
    "labelIds": [
      "INBOX"
    ],
    "historyId": "9876543211",
    "internalDate": "1730913045000",
    "sizeEstimate": 2543,
    "snippet": "This is the beginning of the email message..."
  }
}

Update Message Labels​

Add or remove labels from a message | key: updateLabels

InputNotesExample
Labels to Add

Gmail labels to add to the message.

["INBOX", "IMPORTANT"]
Connection

The Connection to use for Gmail Authorization.

Message ID

The unique identifier of the Gmail message.

18c1e2a4b5f6g7h8
Labels to Remove

Gmail labels to remove from the message.

["SPAM", "UNREAD"]
Gmail User ID (optional)

The user ID or email address to query. Use 'me' for the currently authenticated user (default).

me

{
  "data": {
    "id": "18c2f4b3e8a9d7f6",
    "threadId": "18c2f4b3e8a9d7f6",
    "labelIds": [
      "INBOX",
      "IMPORTANT",
      "STARRED"
    ]
  }
}

Changelog​

2025-11-21​

Added New and Updated Emails polling trigger to check for mailbox changes at scheduled intervals

2025-11-14​

Fixed an issue with Raw Request and Service Account authentication.

2025-10-13​

Added subject impersonate user input option for enhanced email management capabilities.