Only show these results:
public-beta

Enable Microsoft Graph Events permissions in Nylas v2

This feature is in public beta. It might contain bugs, and might change before it is generally available.

Nylas v2 offers Microsoft Graph permissions for Events only. Nylas recommends using Graph for Events if you currently don't use Nylas for Calendar or Events management. If you currently use Nylas with a Microsoft Azure application, see the Existing customers section for more information.

✨ Nylas v3 includes native support for Microsoft Graph. To learn more, see the v3 documentation.

This page discusses how to enable Events permissions for Microsoft Graph.

Before you begin

Before you start, you need to set up your environment:

Existing customers

If you have an existing Azure app, you can upgrade it to use Microsoft Graph. Next, you need to re-authenticate your Azure app in Nylas:

  1. Log in to the Nylas Dashboard.

  2. Select App settings in the left navigation menu.

  3. From the API version dropdown, select a version between 2.3 and 2.7.

    The "App settings" page. The "API version" selector is set to 2.7.

  4. (Native auth only) Authenticate your connected accounts, using graph as the provider. New Microsoft accounts will be created with a new account_id, and all objects will be re-synced with new IDs.

  5. Delete the connected Microsoft accounts that are not authenticated for Microsoft Graph.

Deleting an account removes all associated data. When you re-authenticate, Nylas re-syncs the account data. The accounts will not have any connection to each other.

⚠️ Due to limitations on the provider, if you decide not to delete your existing connected accounts, and instead only re-authenticate them with the new Azure scopes, Nylas detects that as two separate accounts and bills you accordingly.

For more information about authenticating connected accounts, see the Send Authorization API documentation.

Step 1: Enable Microsoft Graph on the Nylas Dashboard

After you set up your environment, log in to the Nylas Dashboard and follow these steps to enable Microsoft Graph:

  1. Select App settings in the left navigation menu.
  2. From the API version dropdown, select a version between 2.3 and 2.7.

The "App settings" page. The "API version" selector is set to 2.7.

Step 2: Authenticate connected accounts

ℹ️ Nylas supports OAuth only for Microsoft Graph scopes.

The following sections describe how to authenticate your connected accounts using either hosted or native auth.

For more information about authenticating connected accounts, see the Send Authorization API documentation.

Hosted authentication

To authenticate connected accounts using hosted auth, you need to have your Azure app's client ID and secret linked to Nylas. For instructions on how to link these values, see the Create an Azure app guide.

Native authentication

To authenticate connected accounts using native auth, use your Azure app's refresh token, client ID, and client secret. When you make the authorization request, pass graph as the provider, as in the example below.

curl -X POST https://api.nylas.com/connect/authorize -d '{ 
    "client_id": "<NYLAS_CLIENT_ID>",
    "name": "Nyla the Cheetah",
    "email_address": "[email protected]",
    "provider": "graph",
    "settings": {
        "microsoft_client_id":     "<AZURE_CLIENT_ID>",
        "microsoft_client_secret": "<AZURE_CLIENT_SECRET?",
        "microsoft_refresh_token": "<AZURE_REFRESH_TOKEN>",
        "redirect_uri":            "https://example.com/redirect", # Redirect URI that the was originally used to get the refresh token.
    },
    "scopes": "calendar"
}'

Step 3: Set up shared Microsoft calendars (Office 365)

📝 Note: This applies only to Office 365 users and is for Nylas applications using API v2.3 and later. Nylas recommends creating a new application if you want to use shared Microsoft calendars. The new Nylas application requires a separate webhook setup, and the Azure client ID and secret.

Follow these steps to set up shared calendars using native auth:

  1. Request the Calendars.ReadWrite.Shared scope for all accounts that need to use shared calendars.

  2. Pass the refresh tokens to the Send Authorization request to set up native auth for the Email and Contacts scopes.

  3. Pass the same refresh tokens to the Send Authorization request to set up native auth for the Calendar scope.

    ℹ️ Passing the same refresh tokens to both requests creates two separate Nylas accounts, each with their own unique IDs and access tokens.

The selected end users now have access to shared calendars. Be sure to use the access tokens associated with the users' Nylas accounts for requests to the Calendar, Email, or Contacts APIs.

Workaround: Ignore Email and Contacts webhooks

You can ignore webhooks from connected accounts that were authenticated using the Email and Contacts scopes; Nylas automatically syncs calendars for those accounts. If you want to disable webhooks for these accounts, you can create a separate production Nylas application with the Email and Contacts scopes authenticated, then deactivate the event webhook triggers.

If you use this workaround, your organization will have three production Nylas applications:

  1. An application for Google and Exchange accounts.
  2. An application for Office 365 accounts using OAuth.
    • This application uses the Email and Contacts scopes.
    • No event webhooks are generated.
  3. An application for Office 365 accounts using Microsoft OAuth.
    • This application uses the Calendar scope only.
    • Event webhooks are generated for Graph accounts (Nylas API v2.3 or higher only).

❗️ If you are charged multiple times for a single user, contact Nylas support to resolve the issue.