# Using a Pub/Sub notification channel

Source: https://developer.nylas.com/docs/v3/notifications/pubsub-channel/

You can set up a Pub/Sub data connector to receive notifications about activity and changes on the provider. Your project can then consume the notifications, and respond to power your app's logic.

Nylas Pub/Sub notification channels send data to a Pub/Sub topic on Google Cloud, which you can subscribe to for notifications. This is different from the [Pub/Sub you set up for your Google auth app](/docs/dev-guide/provider-guides/google/connect-google-pub-sub/), which allows Google to send data to your Nylas application from Pub/Sub topics.

> **Info:** 
> **Good to know**: Although you set up the Pub/Sub notification channel on Google Cloud, it can receive notifications about events on any of the providers Nylas supports - not just Google.

Pub/Sub is an event-driven queue that you can divide into several "topics" which you can use to segment event notifications. You can then subscribe to different topics to get notifications as they come in, either individually or in batches, during periods of high volume. Pub/Sub queues also let you create a "dead letter" queue to gracefully handle notification delivery delays. These options are ideal for projects where webhook volume, latency, or deliverability are concerns, or where your project requires deliverability guarantees.

You can use a Pub/Sub notification channel along with webhooks, and you can use up to five separate Pub/Sub channels to separate your notifications.

## Before you begin

Before you can start using Pub/Sub channels, you need the following prerequisites:

- A Nylas application.
- Your Nylas application's client ID and API key.
- A Google Cloud Platform (GCP) project.
  - If you're not already using GCP to authenticate Google users, create a GCP project.
  - If you already have a Google project for a Google auth app, you can add the Pub/Sub topic for the notifications to that project.
- The [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) installed.

## Pub/Sub architecture

The Nylas Pub/Sub notification channel stores information that allows Nylas to connect to and send messages into a Pub/Sub topic on Google Cloud, which your project can consume. Each Nylas application can have up to five Pub/Sub channels. ([Contact Nylas Support](/docs/support/#contact-nylas-support) if your project requires more than five channels.)

You can use Pub/Sub as a complete replacement for webhook notifications, or alongside existing webhook architecture. For example, you might use a Pub/Sub channel for notification subscriptions that produce a high volume of messages, but use webhooks for lower volume notification subscriptions.

Each Pub/Sub topic can subscribe to any number of notification triggers so you can split your notifications across separate Pub/Sub topics. For example, you can have one topic that handles all email notifications, and separate ones specifically for new events and event changes.

> **Info:** 
> **Keep in mind**: It might take up to two minutes for you to receive Pub/Sub notifications for newly authenticated grants.

### Set up to handle undeliverable notifications

After Nylas delivers the notification to your Pub/Sub queue, it's up to your project to consume the messages.

Nylas recommends that you create a second Pub/Sub topic for each Pub/Sub channel to serve as a "dead letter queue". This topic allows you to collect notifications that your project is unable to consume, so they don't collect in your notification channel and cause latency issues. You can then replay these notifications later, after you resolve any ingestion issues.

See the [official Pub/Sub documentation on handling message failures](https://cloud.google.com/pubsub/docs/handling-failures#dead_letter_topics) for more information.

## Create the Pub/Sub topic

1. Log in to your Google Cloud console, and [go to the Pub/Sub page](https://console.cloud.google.com/cloudpubsub/topicList).
2. From the **Topics** page, click **Create topic**.
3. In the form that opens, give your topic an ID, and select **Add a default subscription**.

> **Warn:** 
> **Don't use `nylas-gmail-realtime` as the topic ID**. This ID should only be used when you [create a pub/sub topic](/docs/dev-guide/provider-guides/google/connect-google-pub-sub/#create-a-pubsub-topic) for your GCP app.

Make note of the topic name, because you'll use it in the next step.

You can also follow the official Google documentation on creating a Pub/Sub topic [using the Google Console](https://cloud.google.com/pubsub/docs/publish-receive-messages-console#create_a_topic), or using the [Google Cloud CLI](https://cloud.google.com/pubsub/docs/publish-receive-messages-gcloud).

## Configure the Pub/Sub channel topic

Next, configure the Pub/Sub topic so Nylas can publish notification messages to it. For these steps, use the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install).

1. First log in to the CLI tool.

   ```bash
   gcloud auth login
   ```

2. Select the project you created the Pub/Sub topic in.

   ```bash
   gcloud config set project <YOUR_PROJECT_ID>
   ```

3. Next, add the Nylas service account as a publisher to the topic.

   ```bash
   gcloud pubsub topics add-iam-policy-binding <YOUR_TOPIC_ID> --member=serviceAccount:nylas-datapublisher@nylas-gma-mt.iam.gserviceaccount.com --role=roles/pubsub.publisher
   ```

## Create a Pub/Sub notification channel for the topic

Next, connect the Pub/Sub queue to your application. You can do this from the Nylas Dashboard by navigating to the **Notifications** page and clicking **Create Pub/Sub Channel**, or by making a [`POST /v3/channels/pubsub` request](/docs/reference/api/pubsub-notifications/create-pubsub-channel/).

This creates a notification channel and sets up the destination where GCP can send the Pub/Sub messages. This request is also where you select the notification triggers you want to this Pub/Sub channel to subscribe to.

```bash

curl --request POST \
  --url 'https://api.us.nylas.com/v3/channels/pubsub' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --data-raw '{
    "description": "PubSub Test",
    "trigger_types": ["message.send_success"],
    "encryption_key": "",
    "topic": "projects/<YOUR_PROJECT_ID>/topics/<YOUR_TOPIC_ID>",
    "notification_email_addresses": ["leyah@example.com"]
  }'

```

## Compressed Pub/Sub notifications

When you enable compressed delivery by setting `compressed_delivery` to `true` on a Pub/Sub channel, Nylas gzip-compresses the notification payload before publishing it to your Pub/Sub topic.

Nylas adds a `content_encoding: gzip` message attribute alongside the existing `trigger_type` attribute when delivering compressed notifications. To process compressed messages, check for the `content_encoding` attribute on the Pub/Sub message -- if it equals `gzip`, decompress the message data using gzip before parsing the JSON.

Compressed delivery is useful in two situations:

- **Reducing payload size**: Compression can significantly shrink large notifications, reducing bandwidth and improving processing performance.
- **Avoiding firewall issues**: Some firewalls and WAFs inspect message bodies and block content that contains HTML tags. Email message notifications often include HTML content, which can trigger these rules. Compressed payloads are opaque gzip binary data that pass through without being flagged.

To enable compressed delivery, set `compressed_delivery` to `true` when you [create](/docs/reference/api/pubsub-notifications/create-pubsub-channel/) or [update](/docs/reference/api/pubsub-notifications/put-pubsub-by-id/) a Pub/Sub channel.

## Related resources

- [Gmail API incremental sync with historyId](https://cli.nylas.com/guides/if-match-gmail-api) — How historyId, ETags, and If-Match work for sync, and why webhooks and Pub/Sub are simpler alternatives.