public-beta

Enable Microsoft Graph Events permissions in Nylas v2

This feature is in public beta. It is generally stable, but some features might be added or changed before it is generally available.

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

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

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

Before you begin

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

Create a v2 Azure app.
Ensure your Azure app has the required scopes.

Upgrade existing Azure app

If you already have an Azure app, you can upgrade it to use Microsoft Graph.

After you upgrade, you'll need to re-authenticate your Azure app in Nylas:

Log in to the Nylas Dashboard.
(Native Auth only) [Authenticate your connected accounts] using graph as the provider. New Microsoft accounts will be created with new account_ids, and all objects will be re-synced with new IDs.
Delete the connected Microsoft accounts that aren't authenticated for Microsoft Graph.

⛔️ Deleting a connected account removes all of its data. Be sure the Microsoft Graph accounts are correctly set up before you remove the old accounts.

When you re-authenticate accounts, Nylas re-syncs their data. The new accounts have no connection to the old accounts.

If you decide not to delete the old Microsoft accounts, and instead only re-authenticate them with the new Microsoft Graph scopes, Nylas detects them as two separate accounts and bills you accordingly.

Authenticate end users

The following sections describe how to authenticate end users using either Hosted or Native Auth. For more information about authenticating connected accounts, see the Send Authorization API documentation.

Authenticate end users with Hosted Auth

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

Authenticate end users with Native Auth

To authenticate connected accounts using Native Auth, make an authorization request with your Azure app's refresh token, client ID, and client secret.

curl -X POST https://api.nylas.com/connect/authorize -d '{ 
  "client_id": "<NYLAS_CLIENT_ID>",
  "name": "Nyla the Cheetah",
  "email_address": "nyla@example.com",
  "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 was originally used to get the refresh token.
  },
  "scopes": "calendar"
}'

Set up shared Microsoft calendars (Microsoft 365)

📝 This section applies only to Microsoft 365 accounts authenticated to Nylas 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 client ID and secret from your Azure application.

Follow these steps to set up shared Microsoft calendars using Nylas Native Authentication:

Request the Calendars.ReadWrite.Shared scope for all connected accounts that need to use shared calendars.
Pass the refresh tokens in a Send Authorization request to set up Native Auth for the Email and Contacts scopes.
Pass the same refresh tokens in another Send Authorization request to set up Native Auth for the Calendar scope.
- Passing the same refresh tokens in both requests creates two separate Nylas connected accounts, each with their own unique IDs and access tokens.

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

Workaround: Ignore Events webhooks

You can choose to ignore Events webhook notifications from connected accounts authenticated using the Email and Contacts scopes. To do this, you can create a separate Nylas application with the Email and Contacts scopes authenticated, then disable the Event webhook triggers.

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

An application for Google and Microsoft Exchange accounts.
An application for Microsoft 365 accounts using OAuth.
- This application uses the Email and Contacts scopes, but doesn't generate Events webhook notifications.
Another application for Microsoft 365 accounts using OAuth.
- This application uses the Calendar scope only and generates Events webhook notifications for Microsoft Graph accounts.