Receive Gmail push notifications by using Google Cloud Pub/Sub

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 costs involved with polling resources to determine if they have changed.

This guide explains how to set up GCP Pub/Sub in order 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.

1. Create a webhook in Torq

1. Go to Integrations > Triggers, select the Gmail card, and click Add.
2. Enter a meaningful name for the integration and click Add.
3. Copy the endpoint URL to use later.
   

2. Create a Pub/Sub topic in GCP

1. Select the project you want to work on (see prerequisite).
2. Search for the Pub/Sub page. Select Topics and click +CREATE TOPIC.
3. 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 that you use a single topic for all Gmail API push notifications to your application, in this case, Torq.
   

3. Add a subscription to the Pub/Sub topic in GCP

1. In the Pub/Sub page > Topics > select the topic you created and click CREATE SUBSCRIPTION.
   
2. In the Subscription ID field, provide a meaningful name for the subscription.
3. For Delivery type, select Push.
4. In the Endpoint URL field, enter the Torq endpoint URL you copied earlier.
5. Keep the default for the rest of the settings.

4. Grant publish rights on your topic

The GCP Pub/Sub requires that you 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.

1. Return to the Pub/Sub page and select the topic you created.
2. In the right-hand panel, click Add Principal.
3. In the Principal field, type gmail-api-push@system.gserviceaccount.com.
4. For the Role, select Pub/Sub Publisher.
5. Click Save.

5. 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 what changes will actually become push notifications on your webhook.

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.

6. 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 to run every 3 days to make sure the watch request doesn't expire.

7. Extract information from the trigger event

The trigger event data needs to be decoded and processed to be readable. As an example, you can 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 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.