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 API scopes

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

All scopes must include the fully-qualified URI path for the provider. The tables shorten the full scope URIs for space reasons, so be sure to add the provider prefix when requesting scopes.

Messages API scopes

All scopes except https://mail.google.com/ must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/messages` `GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>`	`/gmail.readonly`	`/gmail.modify`
`PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>`	`/gmail.modify`	—
`DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>`	`/gmail.modify`	`https://mail.google.com/` (hard-delete)
`POST /v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose`	`/gmail.readonly`	`/gmail.modify`
`PUT /v3/grants/<NYLAS_GRANT_ID>/messages/clean`	`/gmail.readonly`	—
`POST /v3/grants/<NYLAS_GRANT_ID>/messages/send`	`/gmail.send`	`/gmail.compose` `/gmail.modify`

You need to request the /gmail.send scope if you want to schedule messages to be sent in the future. For more information, see Schedule messages to send in the future.

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/messages` `GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>`	`Mail.Read`	`Mail.ReadWrite` `Mail.Read.Shared` `Mail.ReadWrite.Shared`
`PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>`	`Mail.ReadWrite`	`Mail.ReadWrite.Shared`
`POST /v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose`	`Mail.Read`	`Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`
`PUT /v3/grants/<NYLAS_GRANT_ID>/messages/clean`	`Mail.Read`	—
`POST /v3/grants/<NYLAS_GRANT_ID>/messages/send`	`Mail.ReadWrite` `Mail.Send`	`Mail.ReadWrite.Shared`

You need to request the Mail.ReadWrite and Mail.Send scopes if you want to schedule messages to be sent in the future. For more information, see Schedule messages to send in the future.

Endpoint	Scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/messages` `GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>`	`email` `mail-r`
`PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/smart-compose` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID>/smart-compose` `POST /v3/grants/<NYLAS_GRANT_ID>/messages/send`	`email` `mail-r` `mail-w`

Drafts API scopes

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/drafts` `GET /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`/gmail.readonly`	`/gmail.compose`
`POST /v3/grants/<NYLAS_GRANT_ID>/drafts` `PUT /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`/gmail.compose`	—
`POST /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`/gmail.compose`	`/gmail.modify`

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/drafts` `GET /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`Mail.Read`	`Mail.ReadWrite` `Mail.Read.Shared` `Mail.ReadWrite.Shared`
`POST /v3/grants/<NYLAS_GRANT_ID>/drafts` `PUT /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`Mail.ReadWrite`	`Mail.ReadWrite.Shared`
`POST /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`Mail.ReadWrite` `Mail.Send`	`Mail.ReadWrite.Shared`

Endpoint	Scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/drafts` `GET /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`email` `mail-r`
`POST /v3/grants/<NYLAS_GRANT_ID>/drafts/` `PUT /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/drafts/<DRAFT_ID>`	`email` `mail-r` `mail-w`

Folders API scopes

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/folders` `GET /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/folders` `PUT /v3/grants/NYLAS_GRANT_ID>/folders/<FOLDER_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>`	`/gmail.labels`	`/gmail.modify`

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/folders` `GET /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>`	`Mail.Read`	`Mail.ReadWrite` `Mail.Read.Shared` `Mail.ReadWrite.Shared`
`POST /v3/grants/<NYLAS_GRANT_ID>/folders` `PUT /v3/grants/NYLAS_GRANT_ID>/folders/<FOLDER_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>`	`Mail.ReadWrite`	`Mail.ReadWrite.Shared`

Endpoint	Scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/folders` `GET /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>`	`email` `mail-r`
`POST /v3/grants/<NYLAS_GRANT_ID>/folders/` `PUT /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/folders/<FOLDER_ID>`	`email` `mail-r` `mail-w`

Attachments API scopes

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>`	`/gmail.readonly`	`/gmail.modify`

All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>`	`Mail.Read`	`Mail.ReadWrite` `Mail.Read.Shared` `Mail.ReadWrite.Shared`

Endpoint	Scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>`	`email` `mail-r`

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/contacts` `GET /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>` `GET /v3/grants/<NYLAS_GRANT_ID>/contacts/groups`	`/contacts.readonly` `/contacts.other.readonly` `/directory.readonly`	—
`POST /v3/grants/<NYLAS_GRANT_ID>/contacts` `PUT /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>`	`/contacts`	—

You must request the /contacts.other.readonly scope to access contacts from the inbox source, and /directory.readonly for contacts from the domain source.

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/contacts` `GET /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>` `GET /v3/grants/<NYLAS_GRANT_ID>/contacts/groups`	`Contacts.Read` `People.Read`	—
`POST /v3/grants/<NYLAS_GRANT_ID>/contacts` `PUT /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/contacts/<CONTACT_ID>`	`Contacts.ReadWrite`	—

You must request the People.Read scope to access contacts from the inbox and domain sources.

Calendar API scopes

Google
Microsoft

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/calendars` `GET /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy`	`/calendar.readonly`	`/calendar`
`POST /v3/grants/<NYLAS_GRANT_ID>/calendars` `PUT /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>`	`/calendar`	—
`POST /v3/calendars/availability`	`/calendar.readonly`	`/calendar`

You need to request the /calendar scope if you want to use the primary keyword to reference the primary calendar associated with a grant. For more information about the primary keyword, see Find a calendar ID.

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/calendars` `GET /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/calendars/free-busy`	`Calendars.Read`	`Calendars.ReadWrite`
`POST /v3/grants/<NYLAS_GRANT_ID>/calendars` `PUT /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>`	`Calendars.ReadWrite`	—
`POST /v3/calendars/availability`	`Calendars.Read`	`Calendars.ReadWrite`

Events API scopes

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/events` `GET /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>`	`/calendar.events.readonly`	`/calendar.events` `/calendar` `/calendar.readonly`
`POST /v3/grants/<NYLAS_GRANT_ID>/events` `PUT /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp`	`/calendar.events`	`/calendar`
`GET /v3/grants/<NYLAS_GRANT_ID>/resources`	`/admin.directory.resource.` `calendar.readonly`	—

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/events` `GET /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>`	`Calendars.Read`	`Calendars.ReadWrite`
`POST /v3/grants/<NYLAS_GRANT_ID>/events` `PUT /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>` `POST /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp`	`Calendars.ReadWrite`	—
`GET /v3/grants/<NYLAS_GRANT_ID>/resources`	`Place.Read.All`	—

You need to request the OnlineMeetings.ReadWrite scope if you want to automatically create conferencing details on events. For more information, see Enable autocreate for conferencing.

You need to request the meeting:write:meeting and user:read:user scopes if you want to automatically create conferencing details on events. For more information, see Enable autocreate for conferencing.

Scheduler API scopes

Google
Microsoft

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations` `PUT /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIG_ID>` `GET /v3/grants/<NYLAS_GRANT_ID>/scheduling/availability`	`/calendar.readonly`	`/calendar`
`POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings` `PATCH /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID>`	`/calendar.events`	`/calendar`

Endpoint	Required scopes	Other scopes
`POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations` `PUT /v3/grants/<NYLAS_GRANT_ID>/scheduling/configurations/<CONFIG_ID>` `GET /v3/grants/<NYLAS_GRANT_ID>/scheduling/availability`	`Calendars.Read`	`Calendars.ReadWrite`
`POST /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings` `PATCH /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID>` `DELETE /v3/grants/<NYLAS_GRANT_ID>/scheduling/bookings/<BOOKING_ID>`	`Calendars.ReadWrite`	—

Order Consolidation API scopes

Google
Microsoft

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-order` `GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-shipment` `GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-return`	`/gmail.readonly`	—

All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/).

Endpoint	Required scopes	Other scopes
`GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-order` `GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-shipment` `GET /v3/grants/<NYLAS_GRANT_ID>/consolidated-return`	`Mail.Read`	`Mail.Read.Shared`

Nylas notification scopes

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

All scopes must include the fully-qualified URI path for the provider. The tables shorten the full scope URIs for space reasons, so be sure to add the provider prefix when requesting scopes.

Messages notification scopes

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
`message.send_success` `message.send_failed`	`/gmail.send`	—
`message.created` `message.updated`	`/gmail.metadata`	`gmail.readonly` `/gmail.modify`
`message.bounce_detected`	`/gmail.readonly` `/gmail.send`	`/gmail.modify`

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	Required scopes	Other scopes
`message.send_success` `message.send_failed`	`Mail.ReadWrite` `Mail.Send`	—
`message.created` `message.updated`	`Mail.Read`	`Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`
`message.bounce_detected`	`Mail.Read` `Mail.Send`	`Mail.ReadWrite`

All message.* notifications require the email and mail-r scopes.

Threads notification scopes

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
`thread.replied`	`/gmail.readonly` `/gmail.send`	`/gmail.modify`

Notification trigger	Required scopes	Other scopes
`thread.replied`	`Mail.Read` `Mail.Send`	`Mail.ReadWrite`

All thread.* notifications require the email and mail-r scopes.

Folders notification scopes

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
`folder.created` `folder.updated` `folder.deleted`	`/gmail.metadata`	`/gmail.readonly` `gmail.modify`

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	Required scopes	Other scopes
`folder.created` `folder.updated` `folder.deleted`	`Mail.Read`	`Mail.ReadWrite` `Mail.ReadWrite.Shared` `Mail.Read.Shared`

All folder.* notifications require the email and mail-r scopes.

Contacts notification scopes

Google
Microsoft

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
`contact.updated` `contact.deleted`	`/contact.readonly` `/contacts`	—

Notification trigger	Required scopes	Other scopes
`contact.updated` `contact.deleted`	`Contacts.Read`	`Contacts.Read.Shared` `Contacts.ReadWrite` `Contacts.ReadWrite.Shared`

Calendar notification scopes

Google
Microsoft

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
`calendar.created` `calendar.updated` `calendar.deleted`	`/calendar.events.readonly`	`/calendar.events`

Notification trigger	Required scopes	Other scopes
`calendar.created` `calendar.updated` `calendar.deleted`	`Calendars.Read`	`Calendars.Read.Shared` `Calendars.ReadWrite` `Calendars.ReadWrite.Shared`

Events notification scopes

Google
Microsoft

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
`event.created` `event.updated` `event.deleted`	`/calendar.events.readonly` `/calendar.readonly`	`/calendar.events`

Notification trigger	Required scopes	Other scopes
`event.created` `event.updated` `event.deleted`	`Calendars.Read`	`Calendars.Read.Shared` `Calendars.ReadWrite` `Calendars.ReadWrite.Shared`

ExtractAI notification scopes

Google
Microsoft

All scopes must be prefixed with Google’s URI path (https://www.googleapis.com/auth/).

Notification trigger	Required scopes	Other scopes
`message.intelligence.order` `message.intelligence.tracking` `message.intelligence.return`	`/gmail.readonly`	—

Notification trigger	Required scopes	Other scopes
`message.intelligence.order` `message.intelligence.tracking` `message.intelligence.return`	`Mail.Read`	`Mail.Read.Shared`

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 our Google verification and security assessment guide.