# Setting up Google Pub/Sub

Source: https://developer.nylas.com/docs/provider-guides/google/connect-google-pub-sub/

[Google's Pub/Sub subscription service](https://cloud.google.com/pubsub/?hl=en) allows you to receive webhook notifications from Google in a timely manner. You can either use the [Nylas-maintained set up script](#add-pubsub-with-the-nylas-script) to add Pub/Sub to your app, or [set it up manually](#manually-add-pubsub).

If you plan to use the Nylas Email API with Google, you need to set up Pub/Sub. If you don't plan to use the Nylas Email API with your GCP app (for example, if you're creating a calendar-only project), you can skip this step.

## Before you begin

Before you set up Pub/Sub, you must have [set up a Google provider auth app](/docs/provider-guides/google/create-google-app/).

## Add Pub/Sub with the Nylas script

To simplify the process of installing Pub/Sub, Nylas maintains a script that you can run to automatically provision the GCP resources in Golang.

Before you use the script, make sure your environment is set up properly:

- [Install the Go language](https://go.dev/doc/install).
- [Install the Google Cloud CLI tool](https://cloud.google.com/sdk/docs/install-sdk).
- Ensure that the Pub/Sub and IAM APIs are enabled in your GCP app. You can do this using the `gcloud` CLI:

  ```bash
  gcloud services enable pubsub.googleapis.com
  gcloud services enable iam.googleapis.com
  ```

> **Warn:** 
> **You must set up your Pub/Sub topic and its related resources in the Google auth app that you use to authenticate users with Nylas**.

When your environment is ready, download and run the Nylas script:

1. Download the script from the [Nylas infra-setup repository](https://github.com/nylas-samples/infra-setup) and change your local directory to `google-pubsub-sync`.

   ```bash
   git clone https://github.com/nylas-samples/infra-setup
   cd infra-setup/google-pubsub-sync
   ```

2. Use the `gcloud` CLI to switch the project setup to your GCP app.

   ```bash
   gcloud config set project $<GCP_PROJECT_ID>
   ```

3. Authenticate with your GCP app. Make sure that the account you authenticate with has permission to create Pub/Sub and IAM resources.

   ```bash
   gcloud auth login
   gcloud auth application-default login
   ```

4. Fetch the dependencies for the script.

   ```bash
   go get .
   ```

5. Run the script.

   ```bash
   go run main.go --projectId $<GCP_PROJECT_ID>
   ```

   - If you want to configure your GCP app in an environment other than the U.S., use the `--env` flag, as in the code snippet below. The flag supports the `us`, `eu` and `staging` values.

     ```bash
     go run main.go --projectId $<GCP_PROJECT_ID> --env eu
     ```

6. Save the topic name.

If the script fails with a `403` error with a `SERVICE_DISABLED` message, make sure to enable both the IAM and Pub/Sub APIs in your project using the `gcloud` CLI.

```bash
gcloud services enable pubsub.googleapis.com
gcloud services enable iam.googleapis.com
```

## Manually add Pub/Sub

To manually add Pub/Sub to your GCP app, you must [create a service account](#create-a-google-service-account) and [subscribe to a Pub/Sub topic](#create-a-pubsub-topic).

### Create a Google service account

First, create a service account in your GCP app:

1. From the Google Cloud Platform dashboard, navigate to **IAM & admin > Service accounts**.
2. Select your project and click **Create service account**.
3. Name the account `nylas-gmail-realtime`.
> **Warn:** 
> **Keep in mind**: The service account name must be _exactly_ `nylas-gmail-realtime` for the Nylas connector to work.
4. Optionally, add a description to the service account.
5. Click **Create and continue**.
6. Leave the **Grant this service account access to project** section blank and click **Continue**.
7. Leave the **Grant users access to this service account** section blank.
8. Click **Done**.

The following video walks through the process of creating a service account in the Google Cloud Platform dashboard.

<div style="position: relative; padding-bottom: 56.25%; height: 0;">
  <iframe
    src="https://www.loom.com/embed/b786641b56eb4480a01fc1bf0ba9033c"
    frameborder="0"
    webkitallowfullscreen
    mozallowfullscreen
    allowfullscreen
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
  ></iframe>
</div>

### Create a Pub/Sub topic

Next, create a Pub/Sub topic and subscribe to it.

> **Warn:** 
> **You must set up your Pub/Sub topic and its related resources in the Google auth app that you use to authenticate users with Nylas**.

1. From the Google Cloud Platform dashboard, search for "pub/sub" and select **Pub/Sub**.
2. Click **Create topic**.
3. Enter `nylas-gmail-realtime` as the topic ID, and leave everything else as it is.
> **Warn:** 
> **Keep in mind**: The topic ID must be _exactly_ `nylas-gmail-realtime` for the Nylas connector to work.
4. On the next page, click **Show info panel** if the panel is not already open, and select **Add principal**.
5. Enter `gmail-api-push@system.gserviceaccount.com` in the **New principals** field and set the **role** to **Pub/Sub publisher**.
6. On the Topics page, find the **Subscription** section and click `nylas-gmail-realtime-sub`.
7. Select the subscription and click **Edit**.
8. Change the **Delivery type** to **Push**.
9. Set the **Endpoint URL**:
   - **For the U.S.**, use `https://gmailrealtime.us.nylas.com`.
   - **For the E.U.**, use `https://gmailrealtime.eu.nylas.com`.
> **Info:** 
> **If you plan to use your GCP app for multiple Nylas regions, you must create a Pub/Sub subscription for each region**.
10. Select **Enable authentication** and choose the `nylas-gmail-realtime` service account.
11. Under **Expiration period**, select **Never expire**.
12. When prompted, grant the account the `roles/iam.serviceAccountTokenCreator` role. If the prompt doesn't appear, follow these steps to add the role manually:
    1. From the GCP dashboard, select **IAM & admin > Service accounts**.
    2. Copy the full email address for the `nylas-gmail-realtime` service account. The email address should start with `nylas-gmail-realtime`.
    3. Select the service account.
    4. Navigate to the **Permissions** tab, then find the **Principals** tab at the bottom of the section.
    5. Find the `nylas-gmail-realtime-email` service account and click the **Edit** symbol next to it.
       - If the service account isn't listed, click **Grant access** and paste the email address in the **New principals** field.
    6. In the pop-up that appears, click **Add another role**.
    7. Search for `service account token creator` and select the role.
    8. Click **Save**.
13. Leave the other fields as they are and click **Update**. Google saves your changes, and you're returned to the Subscription page.
14. Save the topic name.

## Add topic name to the Nylas Dashboard

Now that you have a Pub/Sub topic, you can add it to the Nylas Dashboard:

1. From the Nylas Dashboard, select the Nylas application you want to attach the Pub/Sub topic to.
2. Select **Connectors** from the left navigation.
3. Select your Google connector and enter the topic you created in the **Google Pub/Sub topic name** field (for example, `projects/nylas-test/topics/nylas-gmail-realtime`).
4. Save your changes.

Repeat these steps for each Nylas application that needs real-time Gmail message sync.

> **Success:** 
> **If you use the same GCP application for all of your Nylas applications, you can use the same Pub/Sub topic for faster email notifications**.