Using granular scopes to request user data

As you work with Nylas, you’ll need to use scopes to control the level of access Nylas has to your users’ data.

What are scopes?

Granular scopes represent sets of permissions you request from your users, on a per-provider basis. Each provider has its own set of scopes, and your users either approve or reject them when they authenticate with your Nylas application.

IMAP connectors don’t support scopes. For more information, see Creating grants with IMAP authentication.

Nylas scopes

Each of the Nylas APIs and notification triggers requires different scopes to function properly. The tables in the following sections list the Google and Microsoft scopes you need to work with specific Nylas features.

All scopes must include the fully qualified URI path for the provider. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.

The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you’re already using one of the permissive scopes, you don’t need to add the more restrictive scope.

Calendar and Events API scopes

Endpoint	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
GET `/calendars` GET `/calendars/<CALENDAR_ID>` POST `/calendars/free-busy`	`/calendar.readonly` ☑️ `/calendar`	`Calendars.Read` ☑️ `Calendars.ReadWrite`
POST `/calendars` PUT `/calendars/<CALENDAR_ID>` DELETE `/calendars/<CALENDAR_ID>`	`/calendar` ☑️	`Calendars.ReadWrite` ☑️
POST `/calendars/availability`	`/calendar.readonly` ☑️ `/calendar`	`Calendars.Read` ☑️ `Calendars.ReadWrite`
GET `/events` GET `/events/<EVENT_ID>`	`/calendar.events.readonly` ☑️ `/calendar.events` `/calendar` (Required to use `primary` keyword.) `/calendar.readonly`	`Calendars.Read` ☑️ `Calendars.ReadWrite`
POST `/events` PUT `/events/<EVENT_ID>` DELETE `/events/<EVENT_ID>` POST `/events/<EVENT_ID>/send-rsvp`	`/calendar.events` ☑️ `/calendar` (Required to use `primary` keyword.)	`Calendars.ReadWrite` ☑️
GET `/resources`	`/admin.directory.resource.calendar.readonly` ☑️️	`Place.Read.All` ☑️️
Auto-conferencing	Microsoft Teams: `OnlineMeetings.ReadWrite`. Google Meet: No extra scopes required. Zoom: `meeting:write:meeting` and `user:read:user`.

Calendar and Events notification scopes

Notification trigger	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
`calendar.created` `calendar.updated` `calendar.deleted`	`/calendar.events.readonly` ☑️ `/calendar.events`	`Calendars.Read` ☑️ `Calendars.Read.Shared` `Calendars.ReadWrite` `Calendars.ReadWrite.Shared`
`event.created` `event.updated` `event.deleted`	`/calendar.events.readonly` ☑️ `/calendar.readonly` ☑️ `/calendar.events`	`Calendars.Read` ☑️ `Calendars.Read.Shared` `Calendars.ReadWrite` `Calendars.ReadWrite.Shared`

Email API scopes

Endpoint	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
GET `/messages` GET `/messages/<MESSAGE_ID>`	`/gmail.readonly` ☑️ `/gmail.modify`	`Mail.Read` ☑️ `Mail.ReadWrite` `Mail.Read.Shared` `Mail.ReadWrite.Shared`
PUT `/messages/<MESSAGE_ID>` DELETE `/messages/<MESSAGE_ID>`	`/gmail.modify` ☑️	`Mail.ReadWrite` ☑️ `Mail.ReadWrite.Shared`
GET `/drafts` GET `/drafts/<DRAFT_ID>`	`/gmail.readonly` ☑️ `/gmail.compose`	`Mail.Read` ☑️ `Mail.ReadWrite` `Mail.Read.Shared` `Mail.ReadWrite.Shared`
POST `/drafts` PUT `/drafts/<DRAFT_ID>` DELETE `/drafts/<DRAFT_ID>`	`/gmail.compose` ☑️	`Mail.ReadWrite` ☑️ `Mail.ReadWrite.Shared`
POST `/messages/smart-compose` POST `/messages/<MESSAGE_ID>/smart-compose`	`/gmail.readonly` ☑️ `/gmail.modify`	`Mail.Read` ☑️ `Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`
PUT `/messages/clean`	`/gmail.readonly` ☑️	`Mail.Read` ☑️
POST `/messages/send`	`/gmail.send` ☑️ `/gmail.compose` `/gmail.modify`	`Mail.ReadWrite` ☑️ `Mail.Send` ☑️ `Mail.ReadWrite.Shared`
POST `/drafts/<DRAFT_ID>`	`/gmail.compose` ☑️ `/gmail.modify`	`Mail.ReadWrite` ☑️ `Mail.Send` ☑️ `Mail.ReadWrite.Shared`
GET `/folders` GET `/folders/<FOLDER_ID>`	`/gmail.labels` ☑️ `/gmail.modify`	`Mail.Read` ☑️ `Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`
POST `/folders` PUT `/folders/<FOLDER_ID>` DELETE `/folders/<FOLDER_ID>`	`/gmail.labels` ☑️ `/gmail.modify`	`Mail.ReadWrite` ☑️ `Mail.ReadWrite.Shared`
GET `/attachments/<ATTACHMENT_ID>`	`/gmail.readonly` ☑️ `/gmail.modify`	`Mail.Read` ☑️ `Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`
GET `/messages/schedules` GET `/messages/schedules/<SCHEDULE_ID>` DELETE `/messages/schedules/<SCHEDULE_ID>`	No scopes are required because scheduled messages are stored with Nylas. To send scheduled messages, you need `gmail.send` for Google, or `Mail.ReadWrite` and `Mail.Send` for Microsoft.

Email scopes for Yahoo OAuth

If you use Yahoo OAuth to connect to your users’ email inboxes, you must include the following scopes in your Yahoo provider auth app.

📝 Note: All Email notifications require the Yahoo email and mail-r scopes.

Endpoint	Yahoo scopes
GET `/messages` GET `/messages/<MESSAGE_ID>` GET `/drafts` GET `/drafts/<DRAFT_ID>` GET `/folders` GET `/folders/<FOLDER_ID>` GET `/attachments/<ATTACHMENT_ID>`	`email` `mail-r`
PUT `/messages/<MESSAGE_ID>` DELETE `/messages/<MESSAGE_ID>` POST `/drafts` PUT `/drafts/<DRAFT_ID>` DELETE `/drafts/<DRAFT_ID>` POST `/messages/smart-compose` POST `/messages/<MESSAGE_ID>/smart-compose` POST `/messages/send` POST `/drafts/<DRAFT_ID>` POST `/folders` PUT `/folders/<FOLDER_ID>` DELETE `/folders/<FOLDER_ID>`	`email` `mail-r` `mail-w`

Email notification scopes

If your account uses the /gmail.metadata scope, Nylas sends message.*.metadata notifications with limited information. For more information, see Using webhooks with Nylas.

Notification trigger	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
`message.send_success` `message.send_failed`	`/gmail.send` ☑️	`Mail.ReadWrite` ☑️ `Mail.Send` ☑️
`message.created` `message.updated`	`/gmail.metadata` ☑️ `/gmail.readonly` `/gmail.modify`	`Mail.Read` ☑️ `Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`
`message.bounce_detected`	`/gmail.readonly` ☑️ `/gmail.send` ☑️ `/gmail.modify`	`Mail.Read` ☑️ `Mail.Send` ☑️ `Mail.ReadWrite` `Mail.Send`
`thread.replied`	`/gmail.readonly` ☑️ `/gmail.send` ☑️ `/gmail.modify`	`Mail.Read` ☑️ `Mail.Send` ☑️ `Mail.ReadWrite` `Mail.Send`
`folder.created` `folder.updated` `folder.deleted`	`/gmail.metadata` ☑️ `/gmail.readonly` `/gmail.modify`	`Mail.Read` ☑️ `Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`

Order Consolidation API scopes

Endpoint	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
GET `/consolidated-order` GET `/consolidated-shipment` GET `/consolidated-return`	`/gmail.readonly` ☑️	`Mail.Read` ☑️ `Mail.Read.Shared`

ExtractAI webhook scopes

Endpoint	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
`message.intelligence.order` `message.intelligence.tracking` `message.intelligence.return`	`/gmail.readonly` ☑️	`Mail.Read` ☑️ `Mail.Read.Shared`

Contacts API scopes

Endpoint	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
GET `/contacts` GET `/contacts/<CONTACT_ID>` GET `/contact_groups`	`/contacts.readonly` ☑️ `/contacts.other.readonly` ☑️ `/directory.readonly` ☑️	`Contacts.Read` ☑️ `People.Read` ☑️
POST `/contacts` PUT `/contacts/<CONTACT_ID>` DELETE `/contacts/<CONTACT_ID>`	`/contacts` ☑️	`Contacts.ReadWrite` ☑️
To access contacts with the `inbox` source, you need the `contacts.other.readonly` Google scope, and the `People.Read` Microsoft scope. For contacts with the `domain` source, you must use the `directory.readonly` Google scope, and the `People.Read` Microsoft scope.

Contacts notification scopes

Notification trigger	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
`contact.updated` `contact.deleted`	`/contact.readonly` ☑️ `/contacts` ☑️	`Contacts.Read` ☑️ `Contacts.Read.Shared` `Contacts.ReadWrite` `Contacts.ReadWrite.Shared`

Scheduler API scopes

Endpoint	Google Scopes `https://www.googleapis.com/auth/…`	Microsoft Scopes `https://graph.microsoft.com/…`
POST `/scheduling/configurations` PUT `/scheduling/configuration/<SCHEDULER_CONFIG_ID>`	`/calendar.readonly` ☑️ `/calendar`	`Calendars.Read` ☑️ `Calendars.ReadWrite`
GET `/scheduling/availability`	`/calendar.readonly` ☑️ `/calendar`	`Calendars.Read` ☑️ `Calendars.ReadWrite`
POST `/scheduling/bookings` DELETE `/scheduling/bookings/<BOOKING_ID>` PATCH `/scheduling/bookings/<BOOKING_ID>`	`/calendar.events` ☑️ `/calendar`	`Calendars.ReadWrite` ☑️

Google OAuth verification

If your application accesses Google user data with the Google APIs and requests certain scopes, you might have to complete the Google verification process and a separate security assessment process. The processes that you need to complete depends on whether your application requests sensitive or restricted scopes.

Scope type	Required processes	Google policy and requirements
Sensitive	Google verification	Your application must follow Google’s API Services User Data Policy.
Restricted	Google verification and security assessment	Your application must follow Google’s API Services User Data Policy and meet additional requirements for specific scopes.

For more information, see the Google verification and security assessment guide.