Skip to content

Authentication scopes

As you work with Nylas, you’ll need to use authentication scopes to control the level of access Nylas has to your users’ data. This page explains those scopes and how to use them.

What are scopes?

Authentication 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.

You set the scopes that you want to request when you create your provider auth app and any connectors. For more information, see the following documentation:

You can also overwrite the default scopes associated with a connector on a per-request basis. To do this, make a GET /v3/connect/auth request and include the scope string.

Nylas scopes

Each of the Nylas APIs and notification sets requires different scopes to function. 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 ☑️️

Automatic conferencing creation

Microsoft Teams: OnlineMeetings.ReadWrite.
Google Meet: No extra scopes required.
Zoom: meeting:write:meeting and user:read:user.

Calendar and Events notification scopes

Notification triggerGoogle 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

Notification triggerGoogle 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.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.readonly ☑️
/gmail.labels (with refactor)
/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 triggerGoogle 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. Which process or processes you need to complete depends on whether your application requests sensitive scopes or restricted scopes.

Scope typeRequired processesGoogle policy and requirements
SensitiveGoogle verificationYour application must follow Google’s API Services User Data Policy.
RestrictedGoogle verification and security assessmentYour 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.