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?
Section titled “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
Section titled “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
Section titled “Messages 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>/messages GET /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID> | /gmail.readonly | /gmail.modify |
PUT /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID> DELETE /v3/grants/<NYLAS_GRANT_ID>/messages/<MESSAGE_ID> | /gmail.modify | — |
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.
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>/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
Section titled “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 |
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>/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
Section titled “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 |
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>/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
Section titled “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 |
Contacts API scopes
Section titled “Contacts 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>/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.
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>/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
Section titled “Calendar 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>/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.
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>/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
Section titled “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 | — |
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.
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>/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
Section titled “Scheduler API scopes”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 |
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
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
Section titled “Order Consolidation 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>/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
Section titled “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
Section titled “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.
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
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
Section titled “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 |
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
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
Section titled “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.
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
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
Section titled “Contacts notification scopes”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 | — |
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
Notification trigger | Required scopes | Other scopes |
---|---|---|
contact.updated contact.deleted | Contacts.Read | Contacts.Read.Shared Contacts.ReadWrite Contacts.ReadWrite.Shared |
Calendar notification scopes
Section titled “Calendar notification scopes”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 |
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
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
Section titled “Events notification scopes”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 |
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
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
Section titled “ExtractAI notification scopes”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 | — |
All scopes must be prefixed with Microsoft’s URI path (https://graph.microsoft.com/
).
Notification trigger | Required scopes | Other scopes |
---|---|---|
message.intelligence.order message.intelligence.tracking message.intelligence.return | Mail.Read | Mail.Read.Shared |
Google OAuth verification
Section titled “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.