> For the complete documentation index, see [llms.txt](https://docs.sprinthub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sprinthub.com/en/topics/integrations/integration-google-ads-and-gmail/connect-gmail-in-real-time-pub-sub.md).
# 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](https://console.cloud.google.com/).
* 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 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").
2. Click on **New project**, give it a name (e.g., `sprinthub-gmail-pubsub`) and click **Create**.
3. 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).
2. On the Service accounts page, click **Create service account**.
3. Fill in the **Service account name** (e.g.: `sprinthub-pubsub-push`) — the ID and email are generated automatically. The permission steps are optional.
4. 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.
2. In the Topics list, click **Create topic**.
3. 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**.
4. 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:
```
gmail-api-push@system.gserviceaccount.com
```
3. In **Assign roles**, select the role **Editor** (if needed, search for "editor" in the role selector).
4. 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:
```
https://sprinthub-api-XXXX.sprinthub.app/email/webhook/gmail
```
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.
5. 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//topics/`).
> * 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`):
```
[EmailAttendance] ⇢ ENTRY source=pubsub topic=projects/.../topics/gmail-notifications account=... messageId=...
[EmailAttendance] ⇢ ENTRY source=imap account=... messageId=...
```
`source=pubsub` = arrived in real time; `source=imap` = arrived via periodic synchronization.
