--- title: "How to Set Up Google Cloud Pub/Sub for Real-Time Gmail Sync (Private Infrastructure)" description: "Configure Google Cloud Pub/Sub for real-time Gmail inbox sync when using Private Infrastructure (OAuth). Covers topics, subscriptions, permissions, and troubleshooting." url: https://helpcenter.smartlead.ai/en/articles/459-how-to-set-up-google-cloud-pubsub-for-real-time-gmail-sync-private-infrastructure collection: "Setting Up Email Accounts" updated: 2026-09-18 language: en --- # How to Set Up Google Cloud Pub/Sub for Real-Time Gmail Sync (Private Infrastructure) Configure Google Cloud Pub/Sub for real-time Gmail inbox sync when using Private Infrastructure (OAuth). Covers topics, subscriptions, permissions, and troubleshooting. This guide covers the Google Cloud Pub/Sub configuration needed for real-time inbox sync when using **Private Infrastructure (OAuth)** for Gmail. This is a one-time setup inside your own GCP project. Smartlead handles everything else from there. ## What You'll Build You'll create **two Pub/Sub topics** and **two subscriptions** in your own Google Cloud project:

Resource	Name	Purpose
Topic	`smartlead-gmail-pubsub-<customer-id>`	Main topic — Gmail publishes change notifications here
Topic	`smartlead-gmail-pubsub-<customer-id>-dlq`	Dead-letter topic — failed deliveries land here
Subscription	`smartlead-gmail-pubsub-<customer-id>-sub`	Push subscription → Smartlead's webhook endpoint
Subscription	`smartlead-gmail-pubsub-<customer-id>-dlq-sub`	Pull subscription on the DLQ for inspection/replay

Replace `` with the unique ID Smartlead gives you during onboarding. It keeps your resources identifiable and distinct from every other customer's setup. ## Before You Start — Values Smartlead Gives You Your Smartlead onboarding team will provide three values:

Placeholder	Example	Where You Use It
`<customer-id>`	12345	In every topic/subscription name, and in the push URL (customer=)
`<region-code>`	6	In the push endpoint URL (region=)
`<secret>`	(issued separately)	In the push endpoint URL (secret=)

**Final push endpoint** (used in Step 5): ```javascript https://prod.slrealtime.com/api/v1/webhooks/gmail/resourceNotifications?region=&secret=&customer= ``` ## Prerequisites - A Google Cloud project with billing enabled. - An account with `Pub/Sub Admin` (or `Owner`/`Editor`) role on that project. - Your `customer-id`, `region-code`, and `secret` from Smartlead. - The same Google account used to log into Gmail must own the project, or have `Pub/Sub Editor` on it — Google enforces this when notifications are enabled on the mailbox. ## Step 1: Enable the Pub/Sub API 1. Open Google Cloud Console at console.cloud.google.com. 2. Select your project from the project picker. 3. Go to **APIs & Services → Library**. 4. Search **Cloud Pub/Sub API**, click it, then click **Enable**. ![](https://staticfiles.gleap.io/ghelparticle/keAKx5NK3hyH1H30gZ4d6Ix8cnpM99uRxtlfq1QJeTLUNayK9oymrAgrUZGSl2RNTE68wEa89Sj.png) ## Step 2: Create the Main Topic 1. Go to **Pub/Sub → Topics → Create topic**. 2. Fill in: **Topic ID**: `smartlead-gmail-pubsub-`; **Encryption**: Google-managed encryption key (default); **Add a default subscription**: uncheck (you'll create subscriptions manually in Step 5); **Schema**: none; **Message retention**: leave default. 3. Click **Create**. ![](https://staticfiles.gleap.io/ghelparticle/ntYd2MxKsO86AwtK2pYGeO5hp4S4Fd2ArKh7v8Nnb5POlD4hTSQSn7K0Xnri2OQ5WDToa8cVIIR.png) ## Step 3: Create the Dead-Letter Topic (DLQ) Repeat Step 2 with one change: **Topic ID**: `smartlead-gmail-pubsub--dlq`. Pub/Sub retries failed pushes with exponential backoff. After 5 failed attempts, a message is dead-lettered here instead of lost, so it can be inspected or replayed later. ## Step 4: Grant Gmail Permission to Publish Gmail publishes notifications via a Google-managed service account. Grant it `Pub/Sub Publisher` **on the main topic only** — not the DLQ. 1. **Pub/Sub → Topics** → click your main topic. 2. Open the info panel → **Permissions** tab → **Add principal**. 3. Fill in: **New principals**: `gmail-api-push@system.gserviceaccount.com`; **Role**: `Pub/Sub Publisher`. 4. Click **Save**. ![](https://staticfiles.gleap.io/ghelparticle/oz40sbMv14Lf8elkm5LDAfVqzucGalEOABFrB4nfCnEOk2F8TOMr11Af6QIiQGaluKzXFnkb5S2.png) > ⚠ Important: do not add this on the DLQ topic — only Pub/Sub itself writes there. ## Step 5: Create the Main Push Subscription 1. **Pub/Sub → Subscriptions → Create subscription**. ![](https://staticfiles.gleap.io/ghelparticle/dQ8v9MP8a52vKnMQd5gp4tpm5j7gCdfrFnboCKqQbM1Z8z5OiJS1VX1nLkaiyqkIr511LiADXZO.png)

Field	Value
Subscription ID	`smartlead-gmail-pubsub-<customer-id>-sub`
Cloud Pub/Sub topic	your main topic (not the DLQ)
Delivery type	Push
Endpoint URL	`https://prod.slrealtime.com/api/v1/webhooks/gmail/resourceNotifications?region=<region-code>&secret=<secret>&customer=<customer-id>`
Enable authentication	Off
Enable payload unwrapping	Off
Subscription expiration	Never expire
Acknowledgement deadline	10 seconds
Message retention duration	1 day
Retain acknowledged messages	Off
Exactly once delivery	Off
Message ordering	Off

Expand **Dead lettering** and enable it:

Field	Value
Dead-letter topic	your -dlq topic
Maximum delivery attempts	5

Expand **Retry policy**:

Field	Value
Retry policy	Retry after exponential backoff delay
Minimum backoff	10 seconds
Maximum backoff	600 seconds

Click **Create**. ![](https://staticfiles.gleap.io/ghelparticle/QEgfwzgpdx9pZKchHddUcKyRMaRPSmDBTMiYde5f8Mwl69V9bAXg2iMlH8HMxbpNpjKEAzw6347.png) > ℹ When you enable dead-lettering, Google Cloud will prompt you to auto-grant the Pub/Sub service account Pub/Sub Publisher on the DLQ topic and Pub/Sub Subscriber on this subscription. Click Grant if prompted. ## Step 6: Create the DLQ Pull Subscription 1. **Pub/Sub → Subscriptions → Create subscription**.

Field	Value
Subscription ID	`smartlead-gmail-pubsub-<customer-id>-dlq-sub`
Cloud Pub/Sub topic	your -dlq topic (not the main topic)
Delivery type	Pull
Subscription expiration	Never expire
Acknowledgement deadline	10 seconds
Message retention duration	7 days
Retain acknowledged messages	Off
Exactly once delivery	Off
Message ordering	Off
Dead lettering	Off
Retry policy	Retry immediately

Click **Create**. ## Step 7: Verify Your Setup Before notifying Smartlead you're ready, confirm: - Both topics exist (main and -dlq). - Main topic has Pub/Sub Publisher for [gmail-api-push@system.gserviceaccount.com](mailto:gmail-api-push@system.gserviceaccount.com). - Main subscription is Push, points to the main topic, endpoint URL has your correct region/secret/customer values, dead-letter topic is the -dlq topic, max delivery attempts = 5. - DLQ subscription is Pull, points to the -dlq topic, retention = 7 days. Then share with Smartlead onboarding: your **GCP project ID**, your `customer-id`, the **Gmail account email** being connected, and confirmation you used the assigned values in the push URL. ## Troubleshooting

Symptom	Likely Cause	Fix
"Topic not found" during onboarding	Topic name mismatch or wrong project	Double-check topic ID and project ID
"User not authorized" during onboarding	Gmail service account missing Pub/Sub Publisher on main topic	Re-add gmail-api-push@system.gserviceaccount.com as Publisher
"Unacked messages" keeps climbing	Smartlead's endpoint is rejecting pushes	Confirm customer-id, region-code, secret in the push URL exactly match what Smartlead gave you
Messages landing in the DLQ	Pushes failed 5x in a row	Inspect via DLQ subscription → Messages → Pull, and share the messageId with Smartlead support
"Push permission denied" warning	Pub/Sub service account missing publisher rights on DLQ	Re-toggle Dead lettering on the main subscription and accept the auto-grant banner

## Quick Reference ```javascript MAIN TOPIC: smartlead-gmail-pubsub- DLQ TOPIC: smartlead-gmail-pubsub--dlq MAIN SUB: smartlead-gmail-pubsub--sub (Push) DLQ SUB: smartlead-gmail-pubsub--dlq-sub (Pull) GMAIL PUBLISHER: gmail-api-push@system.gserviceaccount.com (main topic only) ```