The Gmail API provides server push notifications that let you watch for changes to Gmail mailboxes. It allows you to eliminate the extra network and compute the costs of polling resources to determine if they have changed.
This guide explains setting up GCP Pub/Sub to receive Gmail push notifications in a Torq webhook to trigger workflows.
Communication Flow
Whenever a change occurs in the Gmail account of interest, for example, a new email received, it will send a publish request to your GCP Pub/Sub Topic, and whoever is subscribed to the Pub/Sub Topic, such as a webhook trigger in Torq, will receive a push notification. Ensure there's an active watch request for the Gmail account you want to monitor.
Prerequisites
Before you get started, set up a GCP service account. A GCP service account is also required in order to use Google steps in Torq workflows.
Create a Webhook in Torq
Go to Build > Integrations > Triggers > Gmail, and click Add.
Enter a meaningful name for the integration and click Add.
Copy the endpoint URL to use later.
Create a Pub/Sub Topic in GCP
Select the project you want to work on (see prerequisite).
Search for the Pub/Sub page. Select Topics and click +CREATE TOPIC.
In the Topic ID field, provide a meaningful name and click CREATE TOPIC.
Warning Due to the GCP Pub/Sub limits on the number of topics, Google recommends using a single topic for all Gmail API push notifications to your application, in this case, Torq.
Add a Subscription to the Pub/Sub Topic in GCP
In the Pub/Sub page > Topics > select the topic you created and click CREATE SUBSCRIPTION.
In the Subscription ID field, provide a meaningful name for the subscription.
For Delivery type, select Push.
In the Endpoint URL field, enter the Torq endpoint URL you copied earlier.
Keep the default for the rest of the settings.
Grant Publish Rights on your Topic
The GCP Pub/Sub requires you to grant Gmail privileges to publish notifications to your topic. To do this, you need to grant publish privileges to gmail-api-push@system.gserviceaccount.com.
Return to the Pub/Sub page and select the topic you created.
In the right-hand panel, click Add Principal.
In the Principal field, type gmail-api-push@system.gserviceaccount.com.
For the Role, select Pub/Sub Publisher.
Click Save.
Create a Mailbox Watch Request
To get push notifications, you need to create and maintain a watch for the Pub/Sub topic you created. The watch will determine which mailbox will be monitored for changes and which changes will become push notifications on your webhook.
The Subscribe Gmail address to watch a PUB SUB pre-defined topic template creates and maintains a watch request. Using the template, you can skip this section and section 6 below.
Use the Gmail Watch Topic step to create a watch:
Gmail access token: an access token generated by the Generate Gmail Token step.
User email: the mailbox to monitor.
Label IDs: a list of labels to include in the watch request. For example, to watch for new incoming emails, provide the INBOX label.
Topic: the topic name is copied from GCP.
Once you've created a watch, you'll get a trigger event for changes in the mailbox you're monitoring according to the labels in the watch request.
The watch will expire after 7 days. We suggest that you create a scheduled workflow to renew the watch automatically.
Renew a Watch Request
Use the Subscribe Gmail address to watch a PUB SUB pre-defined topic template to automatically renew a watch request.
The workflow below will create a watch for newly received emails in the defined user mailbox. Schedule the workflow every 3 days to ensure the watch request doesn't expire.
Extract Information from the Trigger Event
The trigger event data needs to be decoded and processed to be readable. For example, check out one of our templates: Monitor and Handle Gmail Mailbox for Phishing.
Decode the trigger event data by using the Decode base64 step with the input:
{{ $.event.message.data }}Parse the decoded event by using the Add data to context step with the input:
{{ $.decode_gmail_notification.result }}Use the Generate Gmail Token step to generate an access token to use in the Gmail steps.
Use the List Mailbox Changes History step to retrieve all mailbox changes that have occurred since the trigger event.
Use the Get a single message step to get the content of a specific message in a readable format. You can implement a loop to go over all the new messages.
The step output will contain the email in a readable format: sender, date and time when the email was received, subject, receiver, email body, and more.
