Ctrlk
Site SprintHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Connect Gmail in real time (Pub/Sub)

This guide shows, screen by screen, how to configure Google Cloud Pub/Sub so SprintHub can receive Gmail emails in real time in SAC360 (seconds), instead of waiting for periodic synchronization via IMAP (1–5 min).

The screens were captured by going through the real process from scratch (new project). The project/topic/account names used here are examples — replace them with your own.

Summary of what will be created in Google Cloud:

Resource
Example in this guide

Project

sprinthub-gmail-pubsub

Service account

sprinthub-pubsub-push@sprinthub-gmail-pubsub.iam.gserviceaccount.com

Pub/Sub topic

projects/sprinthub-gmail-pubsub/topics/gmail-notifications

Subscription (push)

gmail-notifications-sub

In the end, two values are taken to SprintHub: the topic name and the webhook URL (this last one is already provided on the integration configuration screen).

Prerequisites

  • Google account with access to the Google Cloud Console.

  • Credit card registered with Google Cloud (Google requirement; usage stays within the free tier — in practice, free).

  • The webhook URL of your SprintHub instance, which appears on the Gmail integration configuration screen itself (something like https://sprinthub-api-XXXX.sprinthub.app/email/webhook/gmail). The path /email/webhook/gmail is fixed.

Step 1 — Access the console and sign in

Access https://console.cloud.google.com/ and sign in with your Google account.

Step 2 — Create (or select) the project

  1. Click on the project selector at the top (next to "Google Cloud").

  1. Click on New project, give it a name (e.g., sprinthub-gmail-pubsub) and click Create.

  1. Wait for creation (~30s) and select the newly created project in the project selector.

A newly created project may take a few seconds before access is granted (IAM). If "You need additional access" appears, wait a moment and reload.

Step 3 — Create the service account

  1. In search bar at the top, type service accounts and click the result Service accounts (IAM and admin).

  1. On the Service accounts page, click Create service account.

  1. Fill in the Service account name (e.g.: sprinthub-pubsub-push) — the ID and email are generated automatically. The permission steps are optional.

  1. Click on Create and close. The account appears in the list.

Save the service account email — it will be selected in the push subscription (Step 6). E.g.: sprinthub-pubsub-push@sprinthub-gmail-pubsub.iam.gserviceaccount.com.

Step 4 — Create the Pub/Sub topic

  1. In search bar, type pub/sub and click the product Pub/Sub.

On the first visit, the Cloud Pub/Sub API is automatically enabled for the project.

  1. In the Topics list, click Create topic.

  1. Define the Topic ID (e.g.: gmail-notifications). No need to change anything else — leave the checkbox "Add a default subscription" checked (it creates the subscription we'll edit in Step 6). Click Create.

  1. The topic is created with a default subscription (gmail-notifications-sub).

Step 5 — Authorize Gmail to publish to the topic

Gmail publishes notifications to the topic using a fixed Google service agent. You need to grant it permission.

  1. Still on the topic page, in the permissions panel on the right, click Add principal.

  2. In New principals, paste exactly:

  3. In Assign roles, select the role Editor (if needed, search for "editor" in the role selector).

  1. Click on Save.

Without this step, when enabling real time the error appears User not authorized to publish to topic.

Step 6 — Configure the subscription as Push

The subscription is what turns each topic message into an HTTP call to SprintHub. We are going to edit the default subscription created along with the topic (if it doesn't exist, click Create subscription on the topic).

  1. Open the subscription gmail-notifications-sub and click on Edit.

  2. In Delivery type, select Push.

  3. In Endpoint URL, paste the webhook URL shown on the integration configuration screen in SprintHub:

  4. Check Enable authentication and, in Service account, select the account created in Step 3 (sprinthub-pubsub-push@...). The field Audience can be left blank.

  1. Click on Refresh.

The URL must be valid HTTPS. Since we use service account authentication, there is no need to verify the domain in Google.

Step 7 — Copy the topic name

Go back to the topic and copy the Topic name in full (copy button next to it):

Step 8 — Paste it into SprintHub and enable real time

In SprintHub, go to Settings → Integrations → Gmail account → SAC 360. The real-time configuration is in the section "Real-time reception (Pub/Sub)", at the end of the SAC 360 card (it only appears with "Create tickets automatically" enabled):

  1. Copy the webhook URL shown there (copy button) — it is the same one used in Step 6.

  2. Paste the topic name in the field Google Pub/Sub topic.

  3. Turn on the toggle Receive in real time (Pub/Sub).

Screen notes:

  • The toggle only enables with a valid Pub/Sub Topic format (projects/<project>/topics/<topic>).

  • When saving the integration without a valid topic, real time is automatically disabled (prevents an inconsistent state).

Done — from here on, every new email in the Gmail account generates a ticket/message in SAC360 in seconds, without waiting for IMAP synchronization.

How to verify that it is working

  1. Send a test email to the connected Gmail account.

  2. In a few seconds, the ticket/message should appear in SAC360 (without refreshing).

  3. In the Google Cloud Console: Pub/Sub → Subscriptions → gmail-notifications-sub → Metrics should show "Published messages" and "Delivered messages" increasing.

To debug from the server side, the backend logs distinguish the arrival path (filter by email_attendance):

source=pubsub = arrived in real time; source=imap = arrived via periodic synchronization.

PreviousGoogle Conversion API Parameters (Google Ads Conversion API)
NextIntegrations - Outlook

Last updated

Was this helpful?