Nylas Docs

The Nylas Developer Hub

Welcome to the Nylas developer hub. You'll find comprehensive guides and documentation to help you start working with Nylas as quickly as possible, as well as support if you get stuck. Let's jump right in!

Developer Guide

Authentication Scopes

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.

Nylas Scopes

These scopes are required to make API requests through Nylas. These are requested as part of Native and Hosted Authentication.

Nylas ScopeDescription
email.modifyRead and modify all messages, threads, file attachments, and read email metadata like headers. Does not include send.
email.read_onlyRead all messages, threads, file attachments, drafts, and email metadata like headers—no write operations.
email.sendSend messages only. No read or modify privileges on users' emails. Using email.send as the only scope with Gmail accounts may lead to unexpected threading behavior.
email.folders_and_labelsRead and modify folders or labels, depending on the account type.
email.metadataRead email metadata including headers and labels/folders, but not the message body or file attachments.
email.draftsRead and modify drafts. Does not include send.
calendarRead and modify calendars and events.
calendar.read_onlyRead calendars and events.
room_resources.read_onlyRead available room resources for an account. Room resources for Office 365 is an Admin Consent Required permission.
contactsRead and modify contacts.
contacts.read_onlyRead contacts.

Metadata

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.

Microsoft Scopes

These scopes are required when creating a Office 365 app.

Microsoft ScopeApp ManifestDescription
User.ReadAzure Active Directory GraphSign in and read user profile
offline_access Microsoft GraphMaintain access to data you have given it access to
openidMicrosoft GraphSign users in
profileMicrosoft GraphView users' basic profile
User.ReadMicrosoft GraphSign in and read user profile
EAS.AccessAsUser.AllOffice 365 Exchange OnlineAccess mailboxes via Exchange ActiveSync
EWS.AccessAsUser.AllOffice 365 Exchange OnlineAccess mailboxes via Exchange ActiveSync
EWS.AccessAsUser.AllOffice 365 Exchange OnlineAccess

Gmail Scopes

These scopes are required when creating a app in the Google console.

Google ScopeNylas Scopes
userinfo.emailRequired Google scopes
userinfo.profileRequired Google scopes
openidRequired Google scopes
gmail.composeemail.drafts, email.send
gmail.modifyemail.modify, email.send
gmail.labelsemail.folders_and_labels
gmail.metadataemail.metadata
gmail.sendemail.send
gmail.readonlyemail.read_only
calendarcalendar
calendar.readonlycalendar.read_only
contactscontacts
admin.directory.resource.calendar.readonlyroom_resources.read_only

🚧

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 email.read_only or email.modify.

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.

Service Accounts - Calendar Data Only

Nylas is currently able to onboard Google G Suite and Exchange-based accounts for calendar data only via Service Accounts.

Authenticating Accounts

When authenticating an account using Hosted Auth or Native Auth, you request only the scopes you need. For example if you authenticate with only the calendar scope, then you will get 403 response.

403 Response Example

{
    "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']",
    "type": "api_error"
}

IMAP

Using calendar and/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 email scope is included.

What's Next

Updated about a month ago

Authentication Scopes


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.