Gmail

Overview

The Gmail connector watches a mailbox through Gmail push notifications, so new mail starts a workflow within a second. Each message arrives as a typed event with sender, subject, labels and attachment metadata, and the full message is fetched only when a step needs it. Attachments up to 25 MB can be passed to an agent or stored in Google Drive.

Teams use it to parse vendor invoices from an accounts inbox into NetSuite, to route customer replies to Front or Zendesk and to send a summary when a Stripe dispute needs evidence.

Supported accounts

• Google Workspace mailboxes, including shared and delegated ones

• Personal Gmail accounts for testing

• Domain-wide delegation for service accounts in Workspace

How push notifications work

Tessel calls users.watch on the labels you choose. Gmail publishes a notification to a Cloud Pub/Sub topic that Tessel owns, and Tessel reads the history since the last known historyId to find exactly which messages changed. Duplicate notifications are ignored.

POST /gmail/v1/users/me/watch
{
  "topicName": "projects/tessel-eu/topics/gmail",
  "labelIds": ["INBOX"],
  "labelFilterBehavior": "INCLUDE"
}

POST /gmail/v1/users/me/watch
{
  "topicName": "projects/tessel-eu/topics/gmail",
  "labelIds": ["INBOX"],
  "labelFilterBehavior": "INCLUDE"
}

POST /gmail/v1/users/me/watch
{
  "topicName": "projects/tessel-eu/topics/gmail",
  "labelIds": ["INBOX"],
  "labelFilterBehavior": "INCLUDE"
}

Watch renewal

A Gmail watch expires after seven days. Tessel renews it daily, and if a renewal fails it falls back to reading history so no message is skipped.

Permissions needed

Connect with OAuth or a Workspace service account. Choose read-only if workflows only react to mail. Sending and labeling need broader scopes, which you can add later.

• gmail.readonly for triggers and attachment downloads

• gmail.send to send and reply

• gmail.modify to add labels and create drafts