Nylas supports granular authentication scopes to improve security for your end-users. You can limit the permissions and data Nylas requests during authentication by using the
scopes parameter with either the
/oauth/authorize Hosted Authentication or
connect/authorize Native Authentication endpoints.
If you do not have the required scopes, you will need to re-authenticate the account and you user will need to accept the permissions.
|Send and modify all messages, threads, file attachments, and read email metadata like headers|
|email.modify||Read and modify all messages, threads, file attachments, and read email metadata like headers. Does not include send.|
|email.read_only||Read all messages, threads, file attachments, drafts, and email metadata like headers—no write operations.|
|email.send||Send messages only. No read or modify privileges on users' emails. Using
|email.folders_and_labels||Read and modify folders or labels, depending on the account type.|
|email.metadata||Read email metadata including headers and labels/folders, but not the message body or file attachments.|
|email.drafts||Read and modify drafts. Does not include send.|
|calendar||Read and modify calendars and events.|
|calendar.free_busy||EWS accounts should add this scope to access the free/busy endpoint.|
|calendar.read_only||Read calendars and events.|
|room_resources.read_only||Read available room resources for an account. Room resources for Office 365 is an Admin Consent Required permission.|
|contacts||Read and modify contacts.|
If scopes are not provided during authentication, scopes will default to the following:
Office365, Exchange, and other Microsoft accounts do not offer a scope that mirrors our
email.metadatascope. This means that if your app requests
email.metadata, we will then request a more permissive scope to cover those needs, then restrict access within our system. This will usually result in our requesting a
email.read_only scope in place of
email.metadata. Although Nylas will have the resulting access, the requesting app will not have permissions to access the email body.
These scopes are required when creating a Azure app.
|Microsoft Scope||App Manifest||Description|
|User.Read||Azure Active Directory Graph||Sign in and read user profile|
|offline_access||Microsoft Graph||Maintain access to data you have given it access to|
|openid||Microsoft Graph||Sign users in|
|profile||Microsoft Graph||View users' basic profile|
|User.Read||Microsoft Graph||Sign in and read user profile|
|EAS.AccessAsUser.All||Office 365 Exchange Online||Access mailboxes via Exchange ActiveSync|
|EWS.AccessAsUser.All||Office 365 Exchange Online||Access mailboxes via Exchange ActiveSync|
|Calendar.Read.Shared||Microsoft Graph||Nylas supports Microsoft Graph for events only.|
|Calendar.ReadWrite.Shared||Nylas supports Microsoft Graph for events only|
These scopes are required when creating a app in the Google console.
|Google Scope||Nylas Scopes|
|userinfo.email||Required Google scopes|
|userinfo.profile||Required Google scopes|
|openid||Required Google scopes|
|gmail.readonly||email.read_only. Includes gmail.metadata.|
Inconsistency for Google Accounts
Due to a known bug with the Google API, you should not authenticate Google accounts with the
email.metadata scope if you also intend to use more permissive scopes like
You don't need to combine the more permissive scopes include the less permissive ones in most cases. Combining
metadata with those scopes will cause Google to return 403 errors, and the account in question will not sync properly.
"message": "You do not have access to the required scopes. You provided a token which has the following scopes: ['email.read_only', 'email.send']. You would need a token with at least one of the following scopes: ['email.modify']",
Using calendar or contact scopes without the email scope is only relevant for Google and Exchange accounts. IMAP accounts do not have actual calendars and contacts, but we parse iCalendar files and email participants to populate events and contacts when the