Set up Pub/Sub for your Google application

🔍 If you plan to use the Nylas Email API with Google, you must 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.

Google's Pub/Sub subscription service allows you to receive webhook notifications from Google in a timely manner. You can either use the Nylas-maintained setup script to add Pub/Sub to your app, or set it up manually.

Before you begin

Before you set up Pub/Sub, you must have set up a Google provider auth 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.
Install the Google Cloud CLI tool.
Ensure that the Pub/Sub and IAM APIs are enabled in your GCP app. You can do this using the gcloud CLI:
```
gcloud services enable pubsub.googleapis.com
gcloud services enable iam.googleapis.com   
```

⚠️ You must set up your Pub/Sub topic and its related resources in the Google auth app that you use to authenticate end users with Nylas.

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

Download the script from the Nylas infra-setup repository and change your local directory to google-pubsub-sync.
```
git clone https://github.com/nylas-samples/infra-setup
cd infra-setup/google-pubsub-sync   
```
Use the gcloud CLI to switch the project setup to your GCP app.
```
gcloud config set project $YOUR_GOOGLE_PROJECT_ID   
```
Authenticate with your GCP app. Make sure that the account you authenticate with has permission to create Pub/Sub and IAM resources.
```
gcloud auth login
gcloud auth application-default login   
```
Fetch the dependencies for the script.
```
go get .   
```
Run the script.
```
go run main.go --projectId $YOUR_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.
```
go run main.go --projectId $YOUR_GCP_PROJECT_ID --env eu   
```
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:

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 and subscribe to a Pub/Sub topic.

Create a Google service account

First, create a service account in your GCP app:

From the Google Cloud Platform dashboard, navigate to IAM & admin > Service accounts.
Select your project and click Create service account.
Name the account nylas-gmail-realtime.

⚠️ Keep in mind: The service account name must be exactly nylas-gmail-realtime for the Nylas connector to work.
Optionally, add a description to the service account.
Click Create and continue.
Leave the Grant this service account access to project section blank and click Continue.
Leave the Grant users access to this service account section blank.
Click Done.

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

Create a Pub/Sub topic

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

⚠️ You must set up your Pub/Sub topic and its related resources in the Google auth app that you use to authenticate end users with Nylas.

From the Google Cloud Platform dashboard, search for "pub/sub" and select Pub/Sub.
Click Create topic.
Enter nylas-gmail-realtime as the topic ID, and leave everything else as it is.

⚠️ Keep in mind: The topic ID must be exactly nylas-gmail-realtime for the Nylas connector to work.
On the next page, click Show info panel if the panel is not already open.
In the info panel, click Add principal.
Enter [email protected] in the New principals field and set the role to Pub/Sub publisher.
On the Topics page, find the Subscription section and click nylas-gmail-realtime-sub.
Select the subscription and click Edit.
Change the Delivery type to Push.
Set the Endpoint URL:
- For the U.S., use https://gmailrealtime.us.nylas.com.
- For the E.U., use https://gmailrealtime.eu.nylas.com.
📝 If you plan to use your GCP app for multiple Nylas regions, you must create a Pub/Sub subscription for each region.
Select Enable authentication and choose the nylas-gmail-realtime service account.
When prompted, grant the account the roles/iam.serviceAccountTokenCreator role. If the prompt doesn't appear, follow these steps to add the role manually:
i. From the GCP dashboard, select IAM & admin > Service accounts.
ii. Copy the full email address for the nylas-gmail-realtime service account. The email address should start with nylas-gmail-realtime.
iii. Select the service account.
iv. Navigate to the Permissions tab, then find the Principals tab at the bottom of the section.
v. 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.
  vi. A pop-up is displayed. Click Add another role.
  vii. Search for service account token creator and select the role.
  viii. Click Save.
Under Expiration period, select Never expire.
Leave the other fields as they are and click Update. Google saves your changes, and you're returned to the Subscription page.
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:

From the Nylas Dashboard, click App settings > Authentication.
In the Google auth section, enter the topic you created in the GCP topic name field (for example, projects/nylas-test/topics/nylas-gmail-realtime).

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

💡 You can use the same Pub/Sub topic for all of your Nylas applications.