> 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.sprinthub.com/en/topics/integrations/integration-google-ads-and-gmail/connect-gmail-in-real-time-pub-sub.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.