How to Set Up Google Cloud Pub/Sub for Real-Time Gmail Sync (Private Infrastructure)

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:

Replace <customer-id> 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:

Final push endpoint (used in Step 5):

https://prod.slrealtime.com/api/v1/webhooks/gmail/resourceNotifications?region=<region-code>&secret=<secret>&customer=<customer-id>

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.

Step 2: Create the Main Topic

1. Go to Pub/Sub → Topics → Create topic.

2. Fill in: Topic ID: smartlead-gmail-pubsub-<customer-id>; 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.

Step 3: Create the Dead-Letter Topic (DLQ)

Repeat Step 2 with one change: Topic ID: smartlead-gmail-pubsub-<customer-id>-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: [email protected]; Role: Pub/Sub Publisher.

4. Click Save.

⚠ 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.

Expand Dead lettering and enable it:

Expand Retry policy:

Click Create.

ℹ 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.

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 [email protected].

• 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

Quick Reference

MAIN TOPIC:  smartlead-gmail-pubsub-<customer-id>
DLQ TOPIC:   smartlead-gmail-pubsub-<customer-id>-dlq
MAIN SUB:    smartlead-gmail-pubsub-<customer-id>-sub      (Push)
DLQ SUB:     smartlead-gmail-pubsub-<customer-id>-dlq-sub  (Pull)
GMAIL PUBLISHER: [email protected] (main topic only)