Gmail – Inbox Monitoring

Introduction

Gmail provides a feature that allows you to receive notifications when a user’s mailbox changes – for example, when a new email arrives. Instead of polling with repeated API calls, Gmail can push mailbox change notifications to a Google Cloud Pub/Sub topic you control – making integrations looking to work with emails more responsive and efficient.

Notifications Gmail sends contain a “History ID” property which you can use to fetch recent mails using the Gmail Connector’s “List Email History” Method, followed by the “Get Email” Method.

Setup within Google Cloud Console

1. Enable APIs

• In Google Cloud Console, open your project.
• Navigate to APIs & Services > Library.
• Enable Gmail API.
• Enable Cloud Pub/Sub API.

Both must be enabled in the same Google Project that hosts your OAuth credentials.

2. Create a Pub/Sub Topic

• Go to Pub/Sub > Topics.
• Select Create topic:

• Give the topic a name, e.g. projects/<PROJECT_ID>/topics/gmail-watch-topic

This topic is where Gmail will publish notifications.

3. Grant Gmail Publish Permission

Gmail pushes notifications using Google’s managed service account:

serviceAccount:gmail-api-push@system.gserviceaccount.com

You must grant it the Pub/Sub Publisher role on your topic so Gmail can publish messages.

Within the Google Cloud Console

• Go to Pub/Sub > Topics, then click your topic (e.g. gmail-watch-topic).
• Open the Permissions tab and select Add principal:

• Add gmail-api-push@system.gserviceaccount.com:

• In Select a role: choose Pub/Sub > Pub/Sub Publisher if available (see instructions below if not):

• Click Save to update the topic’s IAM policy.

What to do if “Pub/Sub Publisher” is not listed in your Cloud Console…

In some Google Cloud projects, the Pub/Sub > Pub/Sub Publisher role may not appear in the role picker when assigning permissions through the Cloud Console UI.

If this happens, you must manually grant the role using the Google Cloud CLI (gcloud):

Why is this step required?

Without the Pub/Sub Publisher role:

• Gmail cannot send watch notifications.
• The users.watch API call will fail with a 403 Authorization error.
• No inbox updates will be delivered.

Once this permission is in place, Gmail can successfully publish notification messages to your Pub/Sub topic.

Step A: Identify the Gmail Push Service Account

Gmail publishes notifications using the following Google-managed service account:

gmail-api-push@system.gserviceaccount.com

This account must have permission to publish messages to your Pub/Sub topic.

Step B: Grant the Publisher Role Using gcloud

Run the following command, replacing PROJECT_ID with your Google Cloud project ID:

gcloud pubsub topics add-iam-policy-binding projects/PROJECT_ID/topics/gmail-watch-topic \ --member=serviceAccount:gmail-api-push@system.gserviceaccount.com \ --role=roles/pubsub.publisher

If successful, you will see output confirming that the IAM policy has been updated.

Step C: Verify the Permission

1. Go to Pub/Sub > Topics in the Cloud Console.
2. Select your topic.
3. Open the Permissions tab.
4. Confirm that the principal gmail-api-push@system.gserviceaccount.com is listed and has the role “Pub/Sub Publisher“:

 

4. Create a Subscription (Push)

Create a Push subscription to forward messages directly to your HTTPS endpoint:

• Go to Pub/Sub > Subscriptions.
• Select Create Subscription.

• Enter a subscription name (e.g. gmail-watch-push).
• Select your topic (e.g. gmail-watch-topic).
• Set Delivery type to Push.
• Provide your Endpoint URL where Gmail should send notifications.
  • This is the URL of a Gmail Connector’s “Email Notification” Webhook Method which has been dragged into one of your integrations within Cyclr. See the article on Cyclr Webhook URLs for more.

• Select Create.

5. Create Copyable Webhook

• Within Cyclr, go to the Settings/Edit Connector page of an installed Gmail Connector.
• Expand the “Webhooks – Copyable” Custom Object Method Category.
• Select the Copy this Category button on the right to create a new Method Category for your topic:

• In the Edit Custom Object Category pop-up that opens, there are 4 tabs, each with its own Object Name field used for different properties.

Note: All 4 of the Object Name fields in the popup are Required
* The Topic Name must contain the Topic created within Google’s Cloud Console.
* The other 3 tabs should either have an appropriate value or *.

1. Topic Name: enter the name of your Topic created in Step 2 as the Object Name:

2. Label IDs: this parameter is optional. If not needed set Object Name to “*“:

3. Label Filter Behavior: this parameter is optional. If not needed set Object Name to “*“:

4. User ID: this parameter is optional. If not needed, set Object Name to “*” to have the value “me” used as the User ID:

You can now use the “Email Notification – Copyable” Method in the newly created Method Category within an integration to receive notifications when emails arrive.