Skip to content

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.

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.

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.

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

EndpointRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

EndpointRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

EndpointRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

EndpointRequired scopesOther scopes
GET /v3/grants/<NYLAS_GRANT_ID>/attachments/<ATTACHMENT_ID>/gmail.readonly/gmail.modify

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

EndpointRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

EndpointRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

EndpointRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

EndpointRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

EndpointRequired scopesOther 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

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.

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

Notification triggerRequired scopesOther scopes
message.send_success
message.send_failed
/gmail.send
message.created
message.updated
/gmail.metadatagmail.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 Google’s URI path (https://www.googleapis.com/auth/).

Notification triggerRequired scopesOther scopes
thread.replied/gmail.readonly
/gmail.send
/gmail.modify

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

Notification triggerRequired scopesOther 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 Google’s URI path (https://www.googleapis.com/auth/).

Notification triggerRequired scopesOther scopes
contact.updated
contact.deleted
/contact.readonly
/contacts

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

Notification triggerRequired scopesOther scopes
calendar.created
calendar.updated
calendar.deleted
/calendar.events.readonly/calendar.events

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

Notification triggerRequired scopesOther scopes
event.created
event.updated
event.deleted
/calendar.events.readonly
/calendar.readonly
/calendar.events

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

Notification triggerRequired scopesOther scopes
message.intelligence.order
message.intelligence.tracking
message.intelligence.return
/gmail.readonly

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