Only show these results:
public-beta-v3

Create a Google Application for Nylas v3

The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.

This page explains how to create and configure a Google application to use with the Nylas v3beta API. It should be pretty familiar, but some things are different including:

  • Updated Authorized redirect URI (https://api.us.nylas.com/v3/connect/callback) for Hosted Authentication
  • Reduced number of available scopes to match private preview feature availability
  • cURL request example to connect your GCP to Nylas

Create the Google application

Follow the steps below to create your Google application to use with Nylas API v3beta:

  1. Go to the Google Cloud Console create project page.
    Google Create Project page
  2. Give your project a name.
  3. Select your project Organization and Location.
  4. It can take several minutes for the project to be created. Once complete, you'll return to the dashboard with Create Project notifications.
Google Cloud Platform Dashboard notification for Create Project

Enable Your APIs

  1. From the Google Cloud Platform home page, click APIs and Services > Enable APIs and Services.
    Google Console Enable APIs

  2. Search for and enable the following APIs:

  • Gmail API - Required to read and send messages including drafts and attachments. Needed for threads, labels, drafts, send, files, and neural.
  • Google Calendar API - Required to use the calendar and events endpoints. Required for Scheduler.
  • People API - Required to use the contacts endpoints.
  • Admin SDK API - Enable this if you need access to room information for calendar events.
Google API Library

Configure Your OAuth Screen

You can configure your application's OAuth screen. This is the page users will see when they authenticate your application.

Google OAuth Screen
  • From the Google APIs dashboard, click OAuth consent screen.
  • Choose either Internal or External for your user type.

Internal OAuth Screen

  1. Fill out the required OAuth consent information. Use nylas.com for the Authorized domains.
  2. Click Save and Continue.
  3. Click Add or Remove Scopes.
  4. Select .../auth/userinfo.email, .../auth/userinfo.profile, and openid.
  5. Review the Google scopes and how they map Nylas. Select the scopes needed for your application.
  6. Review the Summary and make sure the information is correct for your application.

External OAuth Screen

  1. Fill out the required OAuth consent information. Use nylas.com for the Authorized domains.
  2. Click Save and Continue.
  3. Click Add or Remove Scopes.
  4. Select .../auth/userinfo.email, .../auth/userinfo.profile, and openid.
  5. Review the Google scopes and how they map Nylas. Select the scopes needed for your application.
  6. At step 3, Test Users, you can skip this for now. We’ll go back and change the app to Production.
  7. Review the Summary and make sure the information is correct for your application.
  8. Click Back to Dashboard.
  9. Under the heading Publishing status, click Publish App.

Publishing your app sets it so that you'll need to authorize users using the Nylas API instead of adding them one at a time to the Google test users. The app will show as unverified until you go through the Google security review.

Google Console App Dashboard

Google Authentication Scopes

Review the scopes and choose the ones needed for your application.

Google scope URI Description
https://www.googleapis.com/auth/userinfo.email Required Google scopes
https://www.googleapis.com/auth/userinfo.profile Required Google scopes
openid Required Google scopes
https://www.googleapis.com/auth/gmail.modify Read, compose, and send email from a Gmail account
https://www.googleapis.com/auth/gmail.readonly View email messages
https://www.googleapis.com/auth/gmail.labels See and edit your email labels
https://www.googleapis.com/auth/gmail.compose Create drafts and send email messages
https://www.googleapis.com/auth/gmail.send Send email messages
https://www.googleapis.com/auth/calendar View, create, edit, and delete calendars and events
https://www.googleapis.com/auth/calendar.readonly View calendars and events
https://www.googleapis.com/auth/calendar.events View and edit events on all calendars
https://www.googleapis.com/auth/calendar.events.readonly View events on all calendars

Create Credentials

  1. Click Create Credentials or Credentials.
  2. Select OAuth client ID.
  3. Select Web Application as the Application Type.
  4. Give the application a name.
  5. Update the Authorized redirect URIs:
    • Hosted Authentication - Use https://api.us.nylas.com/v3/connect/callback
    • Custom Authentication - Use the callback URI for your application.
  6. Click Create.
  7. You’ll see your Client ID and Secret displayed in OAuth client created. Save these somewhere safe as you'll need them for your Nylas application.
Google Console Create Credentials

Add Nylas to Your Application

Adding Nylas as an application owner helps our support team diagnose any issues that you may encounter.

  1. Click the menu, and select IAM & Admin > IAM.
  2. Click Add.
  3. Add [email protected] as an owner.
  4. Click Save.
Google Console IAM

Add Google Pub/Sub subscription

Google PubSub allows you to get webhook notifications in a timely manner from Google.
You can either use the Nylas-maintained PubSub setup script, or set up PubSub manually.

Use the Nylas set up script

To simplify installation, Nylas maintains a script that you can run to automatically provision the GCP resources in Golang.

Before you start, make sure your environment is set up to run the script and Google cloud tools:

  • Install the Go language.

  • Install the gcloud CLI tool.

  • Make sure that you have the PubSub and IAM APIs enabled in your GCP project. You can do this using the gcloud CLI tool:

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

Your Pub/Sub Topic and related resources MUST be set up in the same Google app you use to authenticate accounts with Nylas.

Next, download and run the script:

  1. Download the script from the nylas-samples/infra-setup repository, and change your directory to google-pubsub-sync.

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

  2. Switch the project setup to your GCP project.

    gcloud config set project $YOUR_GOOGLE_PROJECT_ID

  3. Authenticate with GCP.

    Make sure that the account you authenticate with has permission to create PubSub and IAM resources.

    gcloud auth login
    gcloud auth application-default login

  4. Fetch the dependencies for the script.

    go get .

  5. Execute the script.

    go run main.go --projectId $YOUR_GCP_PROJECT_ID
    • To setup in environments other than US, use the --env flag. Supported values are us, eu and staging.
    go run main.go --projectId $YOUR_GCP_PROJECT_ID --env eu
    • If the script fails with a 403 error with a message of SERVICE_DISABLED, make sure to enabled both the IAM and PubSub API in your project:
    gcloud services enable pubsub.googleapis.com
    gcloud services enable iam.googleapis.com

  6. Save the topic name as it will be used again when you create your Integration

Set up Google PubSub manually

To set up Google PubSub manually, first make sure that you have an existing Google application connected to your Nylas application.

Your Pub/Sub Topic and related resources MUST be set up in the same Google app you use to authenticate accounts with Nylas.

Next you create a service account, and subscribe to a Google PubSub topic.

Create a Service Account

  1. Open Service Accounts in the Google Cloud Platform console.

  2. Select your project and click Create Service Account.

  3. Name the account nylas-gmail-realtime.

    The name must be exactly nylas-gmail-realtime for the integration to work.

  4. Leave the Grant this service account access to project and Grant users access to this service account fields blank.

  5. Click Done.

Create a Pub/Sub topic

Your Pub/Sub Topic and related resources MUST be set up in the same Google app you use to authenticate accounts with Nylas.

  1. Search for "pub/sub" in the search bar and select Pub/Sub.

  2. Click CREATE TOPIC.

  3. Enter nylas-gmail-realtime for the topic ID and leave everything else as is. The topic ID listed is required for the integration to work.

  4. On the next page, if it's not already open, click SHOW INFO PANEL.

  5. In the panel, click ADD PRINCIPAL.

  6. Enter [email protected] in the New principals field.

  7. Set the role to Pub/Sub Publisher.

  8. On the Topics page, find the Subscriptions section and click nylas-gmail-realtime-sub.

  9. Select the subscription and click EDIT.

  10. Change the Delivery type to Push.

  11. Fill in the Endpoint URL field:

    • for the US, use https://gmailrealtime.us.nylas.com.
    • for the EU, use https://gmailrealtime.eu.nylas.com.

  12. Select Enable Authentication and choose the service account you made in create a service account.

    If you're setting up multiple regions in a single GCP application, you'll need to create a subscription for each region.

  13. When prompted, grant the roles/iam.serviceAccountTokenCreator to your service account. If the prompt doesn't appear, follow the steps below to add the role to your service account:

    • From the main menu, navigate to IAM & Admin > Service Accounts
    • Copy the full service account email for the service account you created in create a service account (it should start with nylas-gmail-realtime).
    • Select the service account (it should be called nylas-gmail-realtime).
    • Navigate to the Permissions tab and make sure you're on the Principals tab at the bottom.
    • If the service account nylas-gmail-realtime-email isn't listed under principals, click Grant Access and paste the email into the New Principals field.
      • If it's listed, click the Edit icon next to that principal.
    • On the pop-up, click ADD ANOTHER ROLE.
    • Search for service account token creator.
    • Select the role.
    • Click SAVE.

  14. Under Expiration period, select Never expire

  15. Leave the other fields as they are and click Update. The screen saves your changes and returns to the Subscription page.

  16. Copy the Topic Name for the next step.

Add an Integration to your application

The integration object is how you connect your provider application to your Nylas application.

curl -X POST https://api.us.nylas.com/v3/integrations \
  --header 'Authorization: Bearer <API_Key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "google example",
    "provider": "google",
    "settings": {
        "client_id": "<google_cliend_id",
        "client_secret": "<google_client_secret"
        "topic_name": "<google_topic_name"
    },
    "scope": [
        "openid",
        "https://www.googleapis.com/auth/userinfo.email",
        "https://www.googleapis.com/auth/userinfo.profile",
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/gmail.compose",
        "https://www.google.apis.com/auth/gmail.modify"
    ]
}'

Congrats!

You’ve created a Google App and added it to your v3 Nylas application!