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.

To remain secure, Nylas strongly recommends passing only the scopes that your application needs when authenticating a user. Please reference the table below when updating your authentication code to make sure your application requests the minimal amount of access necessary for your app's functionality.

Inconsistency for Google Accounts

Due to a known bug with the Google API, you shouldn't authenticate Google accounts with both email.read_only and email.metadata scopes. Doing so will cause Google to return 403 errors.

Nylas Scope Description
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.
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.read_only Read calendars and events.
room_resources.read_only Read available room resources for an account
contacts Read and modify contacts.
contacts.read_only Read contacts.


To give an example, if your app has functionality for users to send and read messages, but not modify messages, you would use the following scopes: email.read_only,email.send.

Here are several example requests showing how your app might pass these scopes depending on if you use Hosted Authentication, Native Authentication, or a Nylas SDK.

curl --request GET
  --url 'https://api.nylas.com/oauth/authorize'
  -d 'client_id=a1b2c3d4e5f6g7h8'
  -d 'response_type=code'
  -d 'scopes=email.send,email.read_only'
  -d '[email protected]'
  -d 'redirect_uri=https://yourapp.com/nylas-redirect'
curl --request POST
  --url 'https://api.nylas.com/connect/authorize'
  -d '{
    "client_id": "a1b2c3d4e5f6g7h8",
    "name": "Mike Pfister",
    "email_address": "[email protected]",
    "provider": "gmail",
    "settings": {
        "google_refresh_token": "1/y8afalja2jeljfjdasljf2ljfljalsdjfj",
        "google_client_id": "194792837498-bhasdh2hbamddhljiwkdfhamve41.apps.googleusercontent.com",
        "google_client_secret": "Zdjk3jidjsH8749hdfwfuuQ"
    "scopes": "email.send,email.read_only"
require 'nylas'

api = Nylas::API.new(config.nylas_client_id, config.nylas_client_secret, nil)

nylas_token = api.authenticate(
  name: 'Ben Bitdiddle', 
  email_address: '[email protected]',
  provider: :gmail,
  settings: {
    google_client_id: ENV['GOOGLE_CLIENT_ID'],
    google_client_secret: ENV['GOOGLE_CLIENT_SECRET'],
    google_refresh_token: auth_hash[:credentials][:refresh_token]
  scopes: ['email.read_only,email.send']

api_as_user = api.as(nylas_token)
from flask import Flask, session, request, redirect, Response
from nylas import APIClient


redirect_url = ""

# Redirect your user to the auth_url
auth_url = client.authentication_url(
const Nylas = require('nylas');

  appId: CLIENT_ID,
  appSecret: CLIENT_SECRET,

options = {
  loginHint: '[email protected]',
  redirectURI: 'https://localhost/callback',
  scopes: ['email.read_only', 'email.send'],

// Redirect your user to the auth_url
auth_url = Nylas.urlForAuthentication(options);

Any tokens obtained this way have a limited scope, so you won't be able to access out-of-scope endpoints with them. For example, if you authenticated with only calendar scope, then the /messages and /threads endpoints will return a 403 HTTP status code:

    "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"

Granular Scopes for 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.

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.