Nylas

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!

Knowledge Base
Suggest Edits

The Nylas APIs

 

The Nylas Platform provides a modern API that works with existing email providers. It makes it simple and fast to integrate your app with a user's email, contacts, or calendar data, and eliminates the complexity of working with old protocols like IMAP and MIME.

The API is designed around the REST ideology, providing simple and predictable URIs to access and modify objects. Requests support standard HTTP methods like GET, PUT, POST, and DELETE and standard status codes. Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise.

Looking to sync and process mail on-the-fly for many accounts? Check out the Nylas Sync Strategies article in our Knowledge Base for our recommended approach.

v2.0 of the API

These docs pertain to version 2.0 of the API. Check out the API versioning section to learn more about how to switch between versions. You can find docs for version 1.0 here.

Suggest Edits

Introduction

 

There are two ways you can authenticate users to your application. If you don't want to build the frontend for authentication yourself, you can use our Hosted Authentication flow to get started quicker. Keep in mind this may be faster initially, but you'll have less control over the authentication user experience. You do have the ability to update your company logo and name, white labeling the experience for your users.

The other option provides much more control and gives you the ability to natively build an authentication flow into your application. With Native Authentication, a user never has to leave your application to connect their account and you have the freedom to design what the entire process looks like.

Visual Learner?

Check out our guide on Hosted vs Native authentication which includes videos showing what each flow might look like to your end users.

Once you've successfully connected an email account using one of the authentication methods outlined above, you'll have an access_token that allows you to pull email, contact, and calendar data for that email account. To learn more about how to use this access_token to make requests to the Nylas API see this guide.

Nylas access_tokens don't expire automatically!

Regardless if you use Hosted Authentication or Native Authentication to retrieve an account's access_token, it's very important to keep in mind that nylas access_tokens never expire. To revoke an access token, you'll need to explicitly call the /oauth/revoke endpoint. This means if you re-authenticate an account, it's possible you can have two active access_tokens. It's your application's responsibility to keep track of these access tokens and revoke them when appropriate.

You can add up to 10 accounts for free to test your integration during your trial period. If you'd like to add more accounts, you'll need to add your credit card information in the Nylas Dashboard.

Create your developer account

Before you can interact with the Nylas API, you need to sign up for a developer account, which will generate an API client_id and client_secret for you.

Important Billing Implications

A paid account is uniquely defined by both its email address and the server settings used to authenticate. This means accounts may be counted more than once if the same email was authenticated with different server settings. Please see this guide for more info.

Suggest Edits

Hosted Authentication

 

The Nylas platform uses the OAuth 2.0 protocol for simple, effective authorization. Before making API calls on behalf of a user, you need to fetch an access_token that grants you access to their email. Once you've obtained a token, you include it with Nylas API requests as the HTTP Basic Auth Username. Although you'll immediately have access to the API once you authorize an account, it may take some time until all historical messages are synced.

Explicit vs. Implicit OAuth

Nylas supports both two-legged and three-legged OAuth. It's important to identify which flow you should use:

You should use Server-side (explicit, three-legged) OAuth if you'll be using the Nylas API from:

  • backend web services (Ruby on Rails, PHP, Python, etc.)
  • a service that will store a large number of access tokens
  • a service running on Amazon EC2 or another cloud platform

You should use Client-side (implicit, two-legged) OAuth if you'll be using the Nylas API from:

  • a native app on desktop or on mobile
  • a client-side Javascript application
  • any other app that does not have a server component

Server Side (Explicit) Flow

Step 1

From your application, redirect users to https://api.nylas.com/oauth/authorize, with the parameters detailed in /oauth/authorize. Note for this server side flow response_type should be set to code.

Step 2

Nylas will present your user with the correct sign in panel based on their email address. For example, a user with a Gmail address will see the Gmail “Authorize this Application” screen, while a user with a Yahoo address is shown a Yahoo sign in panel.

If (and only if) Nylas cannot auto detect the user's email provider from their address, the user will see a provider selection screen first.

For Exchange users, clicking "Advanced Settings" will enable the user to enter a login name and/or Exchange server. The majority of Exchange users can log on with their email address and auto-detected server details, but some will have to enter this additional information.

Step 3

Once the user has signed in, their browser will be redirected to the redirect_uri you provided. If authentication was successful, Nylas will include a code parameter in the query string.

Make an HTTP POST to https://api.nylas.com/oauth/token to exchange the code for an access_token. See /oauth/token for details. Make sure to securely store the access_token and provide it as the HTTP Basic Auth Username to make API calls on behalf of the user.

Client Side (Implicit) Flow

Step 1

From your application, redirect users to https://api.nylas.com/oauth/authorize, with the parameters detailed in /oauth/authorize. Note for this server side flow response_type should be set to token.

Step 2

Nylas will present your user with the correct sign in flow based on their email address. This is the exact same as step 2 in the server side flow.

Step 3

Once the user has signed in, their browser will be redirected to the redirect_uri you provided. If authentication was successful, Nylas will include a token parameter in the query string. That's it! We recommend storing the access_token and then removing it from the URL fragment with JavaScript. This is the token you will provide as a HTTP Basic Auth Username to make API calls on behalf of the user.

Note:

If you're building a mobile app or desktop application, you may want to use a custom URL scheme to listen for the redirect to happen in the user's web browser. For example, myapp://app/auth-response.

Suggest Edits

/oauth/authorize

 
gethttps://api.nylas.com/oauth/authorize
curl --request GET \
  --url 'https://api.nylas.com/oauth/authorize?client_id=client_id&response_type=response_type&scope=email&login_hint=login_hint&redirect_uri=redirect_uri'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/oauth/authorize',
  qs: 
   { client_id: 'client_id',
     response_type: 'response_type',
     scope: 'email',
     login_hint: 'login_hint',
     redirect_uri: 'redirect_uri' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/oauth/authorize?client_id=client_id&response_type=response_type&scope=email&login_hint=login_hint&redirect_uri=redirect_uri")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/oauth/authorize?client_id=client_id&response_type=response_type&scope=email&login_hint=login_hint&redirect_uri=redirect_uri");

xhr.send(data);
import requests

url = "https://api.nylas.com/oauth/authorize"

querystring = {"client_id":"client_id","response_type":"response_type","scope":"email","login_hint":"login_hint","redirect_uri":"redirect_uri"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

client_id
string
required

Your Nylas Developer App client_id

response_type
string
required

code for server side, token for client side

scope
string
required

Set to email

login_hint
string
required

The user’s email address, if known

redirect_uri
string
required

The URI to which the user will be redirected once authentication completes. This must match a URI registered in the developer dashboard.

state
string

Optional arbitrary string that is returned as a URL parameter in your redirect_uri. You can pass a value here to keep track of a specific user’s authentication flow. Also may be used to protect against CSRF attacks

 
Suggest Edits

/oauth/token

 
posthttps://api.nylas.com/oauth/token
curl --request POST \
  --url 'https://api.nylas.com/oauth/token?client_id=client_id&client_secret=client_secret&grant_type=authorization_code&code=code'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/oauth/token',
  qs: 
   { client_id: 'client_id',
     client_secret: 'client_secret',
     grant_type: 'authorization_code',
     code: 'code' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/oauth/token?client_id=client_id&client_secret=client_secret&grant_type=authorization_code&code=code")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/oauth/token?client_id=client_id&client_secret=client_secret&grant_type=authorization_code&code=code");

xhr.send(data);
import requests

url = "https://api.nylas.com/oauth/token"

querystring = {"client_id":"client_id","client_secret":"client_secret","grant_type":"authorization_code","code":"code"}

response = requests.request("POST", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

client_id
string
required

Your Nylas Developer App client_id.

client_secret
string
required

Your Nylas Developer App client secret.

grant_type
string
required

Set to authorization_code

code
string
required

The authorization_code returned from /oauth/authorize step

 
Suggest Edits

/oauth/revoke

 
posthttps://api.nylas.com/oauth/revoke
curl -X POST https://api.nylas.com/oauth/revoke --user ACCESS_TOKEN_TO_REVOKE:
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

You can easily revoke an access token by issuing a POST request to the following endpoint. Include the to-be-revoked access token as the HTTP Basic Auth username.

A 200 status code response with an empty body signifies that the token has been successfully revoked and can no longer be used.

Suggest Edits

Authorization Errors

 

In some scenarios, authentication can fail and you need to display an error message to the user. In these cases, Nylas will include additional parameters when calling your redirect_uri. After presenting the error, you should restart the authorization process.

Attribute Description
error string access_denied, or another error type
reason string A more detailed explanation of the error you may be presented to the end user.
Suggest Edits

Re-authentication

 

When a user's credentials or server settings (for IMAP/ SMTP or Exchange) changes, the account will stop syncing and its status will change to 'invalid-credentials'. For the account sync to resume, you must ask the user to go through the authentication flow again with their new credentials or server settings.

For a credentials change, once the user has re-authenticated, account sync simply resumes.

Important note!

For a server settings change, for example if the user changes the IMAP/ SMTP or Exchange server endpoint, all previously synced Nylas API object ids for the account will be invalidated. The user will be associated with a new account and account_id, and the Nylas API token returned from reauthentication will point to this account.
Your application must detect this new account_id and take appropriate measures to invalidate any existing IDs you have cached.

Suggest Edits

Native Authentication

 

This is a set of endpoints for programmatically creating and updating accounts on Nylas Cloud. It allows you to build a signup form for a user to connect their mailbox to your application.

Connecting a new account is a two-step process, and follows semantics similar to OAuth. The first step is verifying credentials from a user, and the second step is associating this new account with your application in order to receive an API access token.

There are two main endpoints:

https://api.nylas.com/connect/authorize for authenticating a mailbox
https://api.nylas.com/connect/token for connecting the mailbox to your Nylas Cloud app

All API requests must be made over SSL (HTTPS). The Nylas API is not available via unencrypted HTTP.

Suggest Edits

/connect/authorize

This endpoint is where your application sends mailbox credentials to verify they are correct. This begins the connection process.

A successful authentication will return your application a JSON encoded body with a single code parameter. In the next step, your server backend should exchange this code for an access token, which can then be used to make API requests.

 
posthttps://api.nylas.com/connect/authorize
curl -X POST https://api.nylas.com/connect/authorize -d '{ 
    "client_id":     "nylas_client_id",
    "name":          "Erlich Bachman",
    "email_address": "erlich@aviato.com",
    "provider":      "gmail",
    "settings":      {
      "google_client_id":     "google_api_client_id",
      "google_client_secret": "google_api_client_secret",
      "google_refresh_token": "google_api_refresh_token"
    }
  }'
curl -X POST https://api.nylas.com/connect/authorize -d '{
  "client_id":     "nylas_client_id",
  "name":          "Erlich Bachman",
  "email_address": "erlich@aviato.com",
  "provider":      "exchange",
  "settings":      {
    "username": "erlich@aviato.com",
    "password": "makingtheworldabetterplace"
  }
}'
curl -X POST https://api.nylas.com/connect/authorize -d '{
  "client_id":     "nylas_client_id",
  "name":          "Erlich Bachman",
  "email_address": "erlich@aol.com",
  "provider":      "aol",
  "settings":      {
    "password": "makingtheworldabetterplace"
  }
}'
curl -X POST https://api.nylas.com/connect/authorize -d '{
  "client_id":     "nylas_client_id",
  "name":          "Erlich Bachman",
  "email_address": "erlich@aviato.com",
  "provider":      "imap",
  "settings":      {
    "imap_host":     "imap.aviato.com",
    "imap_port":     12345,
    "imap_username": "erlich.bachman",
    "imap_password": "makingtheworldabetterplace",
    "smtp_host":     "smtp.aviato.net",
    "smtp_port":     12346,
    "smtp_username": "erlich.bachman",
    "smtp_password": "makingtheworldabetterplace",
    "ssl_required":  true
  }
}'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{"code": "the response code"}
{
  "message": "Please include the missing fields", 
  "type": "auth_error", 
  "missing_fields": ["provider"], 
  "error": "Missing fields."
}
{
	"message": "Specific info about the error included here",
  "type": "auth_error",
  "error": "authentication_failed"
}

Body Params

client_id
string
required

Your client_id from the Nylas Developer console.

name
string
required

The full name of the user. e.g. “John Snow”.

email_address
string
required

The user’s email address.

provider
string
required

One of gmail, yahoo, exchange, outlook, imap, icloud, hotmail, or aol. Note that the format of the settings object below is dependent upon this field.

settings
object
required

Dependent on which provider you are connecting to. See provider specific settings.

 
reauth_account_id
string

Optional existing account_id to re-authenticate. This is useful if the account has invalid credentials.

 

Provider Specific Settings

Depending on the provider body parameter you include you'll need to send a different settings object in your request to /connect/authorize. Here are the four possible settings objects you might need to include.

"settings": {
  "google_client_id":     "google_api_client_id",
  "google_client_secret": "google_api_client_secret",
  "google_refresh_token": "google_api_refresh_token"
}
"settings": {
  "username": "erlich@aviato.com",
  "password": "makingtheworldabetterplace",
  "eas_server_host": "exchange.aviato.com",
}
"settings": {
	"password": "makingtheworldabetterplace"
}
"settings": {
  "imap_host":     "imap.aviato.com",
  "imap_port":     12345,
  "imap_username": "erlich.bachman",
  "imap_password": "makingtheworldabetterplace",
  "smtp_host":     "smtp.aviato.net",
  "smtp_port":     12346,
  "smtp_username": "erlich.bachman",
  "smtp_password": "makingtheworldabetterplace",
  "ssl_required":  true
}

Google Apps Additional Settings

You need three pieces of information before you can authorize a Google account through Nylas' APIs. First is the Google google_client_id and google_client_secret that you should receive after creating your application in Google's Developer Console. The final piece is a google_refresh_token which is what Google will give you after a user approves access to their account.

Please ensure that all of the following scopes are enabled when you redirect your user to authenticate with google:

https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://mail.google.com/
https://www.google.com/m8/feeds
https://www.googleapis.com/auth/calendar

To learn about how to create a Google application that will work with Nylas, follow the setup guide here. You can also learn more about this process in Google's documentation.

Get a refresh_token, not an access_token!

Be sure that you've received a long-term refresh_token from Google rather than an access_token, since the access token will expire in an hour.

Microsoft Exchange ActiveSync additional settings

Nylas Cloud can sync nearly all Exchange accounts. The provider attribute should be set to exchange.

The eas_server_host value is optional. If omitted, Nylas Cloud will attempt AutoDiscovery for the server host (endpoint).

Other known IMAP providers

You probably noticed that the only field you need to include in the settings object for known IMAP providers is a password. Nylas makes it easy to authenticate to common providers by passing along other IMAP connection info automatically. You'll only need to include a password in the settings object for these known providers: yahoo, icloud, hotmail, and aol.

If your user has their own IMAP server, you'll need to provide the full settings object listed in the Generic IMAP Provider Settings example above.

Regular IMAP / SMTP

Your user can also connect a regular IMAP+SMTP account by specifying the full connection settings in the settings object. Some are optional and default to a standard value. See the Example Generic IMAP Provider Settings above.

IMAP and SMTP servers are currently authenticated using username+password based login authentication. If your application needs other authentication mechanisms (such as Kerberos, GSSAPI, or S/KEY) please get in touch with Nylas support

Notice about POSTing to /connect/authorize

We recommend POSTing these values directly to api.nylas.com using AJAX from your web application. By sending these directly, your app will never be required to manipulate or store passwords for a user's mailbox. (You don't even want to take the chance of logging these by accident!)

Suggest Edits

/connect/token

This endpoint is where your application exchanges the code received from /connect/authorize and receives an access_token. This associates the mailbox with your Nylas Cloud app.

 
posthttps://api.nylas.com/connect/token
  curl -X POST "https://api.nylas.com/connect/token" -d '{
    "client_id": "the-client-id",
    "client_secret": "the-client-secret",
    "code": "the-code"
  }'
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "account_id": "the-account-id",
  "access_token": "the-token",
  "email_address": "erlich@aviato.com",
  "id": "the-id",
  "name": "Erlich Bachman",
  "object": "account",
  "organization_unit": "folder",
  "provider": "eas",
  "sync_state": "running"
}

Body Params

client_id
string
required

Your client_id from the Nylas Developer console.

client_secret
string
required

Your client_secret from the Nylas Developer console.

code
string
required

The value returned from calling /connect/authorize

 

A successful response from this will be an account object with an access_token attribute. Once you’ve obtained a token, you include it with Nylas API requests as the HTTP Basic Auth Username.

You can remove this account from your Nylas Cloud app in the Nylas API console.

Never send your client secret to a browser!

This request should be made from your server. It's important that you never send your client secret to a browser. In order to do this, your browser JS code should securely send the received code in the previous step to your web app, which in turn makes the request to /connect/token.

Suggest Edits

Accounts

 

An account corresponds to an email address, mailbox, and optionally a calendar. When connecting to the Nylas API, a specific access token gives you access to a specific account’s data.

The Account object

Responses for the Account object are encoded as UTF-8 JSON objects with the following attributes:

attribute type description
id string Globally unique object identifier
object string A string describing the type of object (value is "account")
account_id string Reference to parent account object (self-referential in this case)
name string Full name of the user, used as the default "from" name when sending mail.
email_address string The canonical email address of the account. For Gmail accounts, this removes periods and plus suffixes.
provider string Which provider backs the account, e.g. gmail or eas. See Supported Providers for a full list.
organization_unit string Either "label" or "folder" depending on the provider capabilities
sync_state string The syncing status of the account. See the Sync status documentation for possible values.
linked_at int32 Unix timestamp of the time this account was originally connected to Nylas.

Folders vs. Labels

Messages and threads in accounts can either be organized around folders, or around labels. This depends on the backend provider. For example, Gmail uses labels whereas Yahoo! Mail uses folders.

Labels and Folders have fundamentally different semantics and these are preserved in the API. The core difference is that a message can have more than one label, versus only having one folder.

The organization_unit attribute on the account object indicates whether the account supports folders or labels. Possible values are folder or label. For more details on format and usage, see the related documentation on Folders and Labels.

Suggest Edits

/account

An access token can be used to request information about the account it corresponds to. This includes information such as the end-user’s name, email address, and backend mailbox provider.

 
gethttps://api.nylas.com/account
curl --request GET \
  --url https://api.nylas.com/account
var request = require("request");

var options = { method: 'GET', url: 'https://api.nylas.com/account' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/account");

xhr.send(data);
import requests

url = "https://api.nylas.com/account"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "awa6ltos76vz5hvphkp8k17nt",
    "account_id": "awa6ltos76vz5hvphkp8k17nt",
    "object": "account",
    "name": "Ben Bitdiddle",
    "email_address": "benbitdiddle@gmail.com",
    "provider": "gmail",
    "organization_unit": "label",
  	"sync_state": "running",
    "linked_at": 1470231381,
}

Headers

Authorization
string

access_token passed as HTTP Basic Auth username. See access token guide

 
Suggest Edits

Single Account Sync States

 

The sync_state field for an account can take one of the following statuses:

Status Action required
running Sync is successfully running. No action required.
invalid Authenticating failure with mail server. You should prompt the user to re-authorize.
stopped Sync is stopped. This can happen for a variety of reasons. If you are adding accounts beyond the limits of the free tier, some may be stopped until you upgrade your Nylas application. It can also occur when we encounter unexpected errors. These unexpected errors most commonly originate from incompatibilities with upstream providers or temporary outages.

Note: The sync_state for this individual account endpoint is a simplified set of values relative to the sync_state that is available from the Account Management API.

Suggest Edits

Account Management

 

These endpoints allow for account management outside the developer console interface. You can list, cancel, reactivate, and delete accounts associated with your application.

Special Authentication Needed

This endpoint uses the management API domain with different authentication from the rest of the Nylas API.

Suggest Edits

Listing all accounts

 
gethttps://api.nylas.com/a/client_id/accounts
curl --request GET \
  --url https://api.nylas.com/a/client_id/accounts \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/a/client_id/accounts',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/a/client_id/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/a/client_id/accounts");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/a/client_id/accounts"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
  {
    "account_id": "622x1k5v1ujh55t6ucel7av4",
    "billing_state": "free",
    "id": "622x1k5v1ujh55t6ucel7av4",
    "sync_state": "running"
  },
  {
    "account_id": "123rvgm1iccsgnjj7nn6jwu1",
    "billing_state": "paid",
    "id": "123rvgm1iccsgnjj7nn6jwu1",
    "sync_state": "running"
  }
]

Path Params

client_id
string
required

The client_id of your Nylas developer application

Headers

Authorization
string
required

client_secret passed as HTTP Basic Auth username

 

Often you may want to retrieve a list of all users who have connected to your application. You can use the /accounts endpoint within your application namespace. This will list the accounts associated with your Nylas developer application.

Default Limit

Note that the default limit is set to 100 accounts in the response object. Please see our pagination section to modify that limit.

Instead of using a connected email account’s token, you use your client_secret for the Basic Auth username which can be found in the developer console.

Responses are encoded as UTF-8 JSON objects with the following attributes.

attribute type description
account_id string Reference to parent account object (self-referential in this case)
billing_state string The billing state for the account. Can be free, paid, cancelled, or deleted
id string Globally unique object identifier
sync_state string The current sync state for the account. See all sync states
Suggest Edits

Listing an account

Get information for a single account

 
gethttps://api.nylas.com/a/client_id/accounts/id
curl --request GET \
  --url https://api.nylas.com/a/client_id/accounts/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/a/client_id/accounts/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/a/client_id/accounts/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/a/client_id/accounts/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/a/client_id/accounts/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

client_id
string
required

The client_id of your Nylas developer application

id
string
required

The account_id

Headers

Authorization
string
required

client_secret passed as HTTP Basic Auth username

 
Suggest Edits

Cancel an account

You can cancel paid accounts by using this endpoint.

 
posthttps://api.nylas.com/a/client_id/accounts/id/downgrade
curl --request POST \
  --url https://api.nylas.com/a/client_id/accounts/id/downgrade \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/a/client_id/accounts/id/downgrade',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/a/client_id/accounts/id/downgrade")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/a/client_id/accounts/id/downgrade");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/a/client_id/accounts/id/downgrade"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{ "success": "true" }

Path Params

client_id
string
required

The client_id of your Nylas developer application

id
string
required

The account_id

Headers

Authorization
string
required

client_secret passed as HTTP Basic Auth username

 
Suggest Edits

Re-activate an account

You can re-enable cancelled accounts to make them active again using this endpoint.

 
posthttps://api.nylas.com/a/client_id/accounts/id/upgrade
curl --request POST \
  --url https://api.nylas.com/a/client_id/accounts/id/upgrade \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/a/client_id/accounts/id/upgrade',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/a/client_id/accounts/id/upgrade")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/a/client_id/accounts/id/upgrade");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/a/client_id/accounts/id/upgrade"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{ "success": "true" }

Path Params

client_id
string
required

The client_id of your Nylas developer application

id
string
required

The account_id

Headers

Authorization
string
required

client_secret passed as HTTP Basic Auth username

 
Suggest Edits

Deleting an account

 

If you would like for an account's data to be completely removed from Nylas' servers, follow these steps to queue the account for deletion:

  1. Revoke the account's access token
  2. Cancel the account.

Please note once you follow these steps, the account will be queued for deletion. It can take up to 30 days for an account's data to be completely removed. Furthermore, if the user re-connects their account and authenticates again, their account won't be deleted.

Suggest Edits

Account Management Sync States

 

Sometimes, syncing cannot complete successfully for an account, or it might get interrupted. In the event of a recoverable failure, you will see a notification in the Nylas dashboard and one of the following status messages in the Accounts API:

Status Action required
running Sync is successfully running. No action required. It means we are up to date and listening for new changes.
invalid-credentials Authenticating failure with mail server. You should prompt the user to re-authorize.
stopped Sync is stopped. This can happen for a variety of reasons. If you are adding accounts beyond the limits of the free tier, some may be stopped until you upgrade your Nylas application. It can also occur when we encounter unexpected errors. These unexpected errors most commonly originate from incompatibilities with upstream providers or temporary outages.
exception This means an unexpected error was raised while syncing an account. It can occur if an upstream provider returns an error our sync engine does not yet understand. Please contact support@nylas.com for accounts in this state.

Most sync and connection failures are temporary, but if this persists, check our status page for any known problems and/or contact support.

Credential errors

These occur when the user's account fails authorization. Usually this is because the user has changed their password, revoked their OAuth credentials, or their IMAP/ SMTP or Exchange server endpoint has changed.

Without authorization, no mail operations can successfully complete. In order to make the account active again, you will need to re-authorize the user by asking them to reauthenticate by going through the authentication flow again.

Suggest Edits

Configuration Problems

 

Sometimes you might run into trouble when trying to sync accounts. Here is a list of common problems you might run into.

'All Mail' folder disabled

For Gmail and Google Apps accounts, the Nylas Sync Engine synchronizes the 'All Mail' folder. If a user has disabled IMAP access for this folder, synchronization will fail.

To fix it, the user needs to make sure the 'All Mail' folder has 'Show in IMAP' checked in their Gmail settings. After enabling it, re-authorize the user by restarting the authorization flow.

Full IMAP not enabled

As the Nylas Sync Engine synchronizes mail over IMAP, if IMAP access is not properly enabled for an account or a domain, synchronization will fail. This does not apply to Microsoft Exchange accounts.

The user needs to ensure IMAP is fully enabled for their account. This may involve contacting their domain administrator or hosting provider. Once it is enabled, re-authorize the user.

Connection and sync errors

If temporary connection issues persist, contact support for assistance. Outages or other unscheduled service interruptions are posted on Nylas Status.

Too many connections

Some IMAP configurations limit the number of connections which can be made. If a user has several programs accessing their email account via IMAP, they may run into this error with the Nylas Sync Engine. The resolution is for the user to close other programs which may be accessing their account via IMAP. Gmail users can check which applications they have authorized, and remove any that are no longer being used.

Suggest Edits

Introduction

 

Threads are a first-class object, allowing you to build beautiful mail applications that behave the way users have come to expect. Actions like archiving or deleting can be performed on threads or individual messages.

Nylas threads messages together using a variety of heuristics. On Gmail and Microsoft Exchange accounts, messages will be threaded together as close as possible to the representation in those environments. For all other providers (including generic IMAP), messages are threaded using a custom JWZ-inspired algorithm. (Open source here, for the curious.)

To load all messages for a given thread, you should instead use the messages endpoint with a thread_id filter parameter.

The Thread Object

Responses from the /threads endpoint are encoded as UTF-8 JSON objects with the following attributes:

attribute type description
id string Globally unique object identifier
object string A string describing the type of object (value is "thread")
account_id string Reference to parent account object
subject string Subject of the first message in the thread
unread boolean Indicates whether the thread contains unread messages (mutable)
starred boolean Indicates one or more messages are starred, aka flagged (mutable)
last_message_timestamp unix timestamp Timestamp of the most recent message
last_message_received_timestamp unix timestamp Timestamp of the most recently received message.
(Excludes messages sent by the account.)
last_message_sent_timestamp unix timestamp Timestamp of the most recently sent message in the thread
first_message_timestamp unix timestamp Timestamp when the thread began
participants array List of participant objects computed from all messages in the thread.
snippet string A shortened plain-text preview of the most recent message in the thread
message_ids array Array of IDs for messages within the thread, sorted by their timestamps
draft_ids array Array of IDs for unsent drafts in the thread. May be null or absent
version integer Incrementing value related to thread updates.
You can use this to compare revisions, or invalidate your local cache.
folders array The folder location(s) of a thread, present only if the parent account's organization_unit is folder. Note that threads can span folders, depending on the location of the thread's messages. See the folders docs for more info.
labels array A list of label objects, present only if the parent account's organization_unit is label. These have Gmail-style semantics and can be arbitrarily added and removed from threads.

Supported Modifications

You can make many modifications to the state of threads:

  1. Modify the unread status
  2. Star or unstar the thread
  3. Move the thread to a different folder
  4. Modify the thread's labels

To make these modifications, make an HTTP PUT request to /threads/{id} with any combination of the body parameters specified here.

A note about thread modifications

An operation on a thread is performed on all the messages in the thread. It's a convenient shortcut to perform bulk operations on messages, which is what users have come to expect with modern mail applications.

Filtering, Pagination, and Views with Threads

The threads endpoint supports Filters, Pagination, and Views, making it easy to return a subset of threads in specific folder, from a certain address, with a specific subject, etc.

Thread Filtering

Threads support various combinations of Filters. Check all the query parameters on the /threads endpoint for more information.

Thread Pagination

By default the /threads endpoint will return a maximum of 100 objects. You should paginate through an entire user's mailbox by using the limit and offset URL query parameters. See Pagination for more details about pagination in general. Check all the query parameters on the /threads endpoint for more information.

Thread Views

Threads support the use of Views by including the view query parameter in your request.

The Expanded Threads View expands the threads response to contain message and draft sub-objects. Adding view=expanded will remove message_ids and draft_ids, and include messages and drafts. Note the message and draft sub-objects do not include a body parameter.

Suggest Edits

/threads

 
gethttps://api.nylas.com/threads
curl --request GET \
  --url https://api.nylas.com/threads
var request = require("request");

var options = { method: 'GET', url: 'https://api.nylas.com/threads' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/threads")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/threads");

xhr.send(data);
import requests

url = "https://api.nylas.com/threads"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

view
string

Can be one of ids, count, or expanded. See Views for more info.

limit
int32

Number of objects to return. Often defaults to 100. If set too high, requests may fail to prevent excessively large response bodies.

offset
int32

Zero-based offset from default object sorting. See pagination for more info.

subject
string

Return threads with a matching literal subject

any_email
string

Return threads that have been sent or received from this email address

to
string

Return threads containing messages sent to this email address

from
string

Return threads containing messages sent from this email address

cc
string

Return threads containing messages that were CC'd to this email address

bcc
string

Return threads containing messages that were BCC'd to this email address, likely sent from the parent account. (Most SMTP gateways remove BCC information.)

in
string

Return threads in a given folder, or with a given label. This parameter supports the name, display_name, or id of a folder or label. Note: If you'd like to get all drafts use the /drafts endpoint.

unread
boolean

Return threads with one or more unread messages

starred
boolean

Return threads with one or more starred messages

filename
string

Return threads that contain attachments with the given filename

last_message_before
int32

Return threads whose most recent message was received before this unix timestamp

last_message_after
int32

Return threads whose most recent message was received after this unix timestamp

started_before
int32

Return threads whose first message was received before this unix timestamp

started_after
int32

Return threads whose first message was received after this unix timestamp.

Headers

Authorization
string

access_token as HTTP Basic Auth username

 
Suggest Edits

/threads/{id}

 
gethttps://api.nylas.com/threads/id
curl --request GET \
  --url https://api.nylas.com/threads/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/threads/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/threads/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/threads/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/threads/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The thread_id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/threads/{id}

 
puthttps://api.nylas.com/threads/id
curl --request PUT \
  --url https://api.nylas.com/threads/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.nylas.com/threads/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/threads/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.nylas.com/threads/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/threads/id"

headers = {'authorization': 'Authorization'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The thread_id

Body Params

unread
boolean

Set true to mark as unread, and false to mark as read

starred
boolean

Set trueto star, and false to un-star a thread

folder_id
string

folder_id to move this thread to

label_ids
array of strings

label_ids to apply, overwriting all previous labels on the thread.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Unread status

The unread attribute is set to true if any of the thread's messages are unread. To mark all underlying messages as "read", your application should change the unread attribute to false on the thread. Any change to a thread's unread status will cascade to all messages in the thread.

Changes to the unread status will propagate to the backend mailbox provider, such as Gmail or Exchange.

Starring (flags)

Stars, also know as "flags", are displayed in nearly every mail app, and are an easy way to highlight a specific message. Although most apps usually show stars at the thread level, they are actually an attribute of messages themselves. Changing the starred property of a thread will cause all messages in that thread to be starred or unstarred.

The starred property in the Nylas API is equivalent to stars in Gmail, the IMAP flagged message attribute and Microsoft Exchange message "flags."

Changes to the starred value will propagate to the backend mailbox provider, such as Gmail or Exchange.

Moving a thread

Note about thread folders

This is only supported for accounts where the organization_unit is set to folder. Generally this is all non-Gmail/Google Apps accounts. You can check if an account supports folders by the organization_unit property on the Account object.

The folders attribute of a thread contains an array of folder objects. This is the union of all folders containing messages in the thread. For example, an ongoing discussion thread would likely have messages in the Inbox, Sent Mail, and perhaps the Archive folders.

Your application can move a thread to a new folder by specifying a folder_id, and this will perform the operation on all messages within that thread. Using the Inbox folder ID will move all messages of the thread to the Inbox.

Note that messages in the sent folder are not moved via this batch action.

Modifying labels

Note about labels

This is only supported for accounts where the organization_unit is set to label. Generally this is only Gmail/Google Apps accounts. You can check if an account supports labels by the organization_unit property on the Account object.

Labels are a Gmail-specific way of organizing messages. A message or thread can have multiple labels, enabling more complex queries and email management workflows. The labels attribute of a thread contains an array of Label objects. This is the union of all labels on messages in the thread.

The Nylas platform lets you easily change the labels associated with a message. This change will propagate to the backend mailbox provider (Gmail).

Suggest Edits

Introduction

 

Messages are the fundamental object of the Nylas platform, and the core building block for most email applications. They contain several pieces of information, such as when a message was sent, the sender's address, to whom it was sent, and the message body. They can also contain files (attachments), calendar event invitations, and more.

Security notice about message bodies

Although message bodies are HTML, they are generally not safe to directly inject into a web app. This could result in global styles being applied to your app, or the execution of arbitrary JavaScript.

The Message Object

Responses from the /messages endpoint are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "message")
account_id string Reference to parent account object
thread_id string Reference to parent thread object (all messages have a thread)
subject string Subject line of the message
from array List of name+email pairs the message was sent from. This is usually one object, but can be many.
to array Array of name+email pairs the message was sent to.
cc array Array of name+email pairs the message was cc'd to.
bcc array Array of name+email pairs the message was bcc'd to. In received mail this is nearly always empty (for obvious reasons).
reply_to array Array of name+email pairs replies should be sent to.
date unix timestamp Timestamp of the date the message was received by the mail server. Note this may be different from the unverified Date header in raw message object.
unread boolean Message is unread, default for new incoming mail (mutable)
starred boolean Starred or flagged state (mutable)
snippet string A shortened plain-text preview of the message body
body string The full HTML message body. Messages with only plain-text representations are up-converted to HTML.
files array Array of File objects, if message includes attachments
events array Array Event objects, if message includes calendar invites
folder folder object A single folder object indicating the location of the message, present only if the parent account's organization_unit is folder. This property can be changed to move the message to a different folder.
labels array An list of Label objects, present only if the parent account's organization_unit is label. These have Gmail-style semantics and can be arbitrarily added and removed from messages.

Supported Modifications

Like with Threads, you can make many modifications to the state of messages. You can:

  1. Modify the unread status
  2. Star or unstar the message
  3. Move the message to a different folder
  4. Modify the message's labels

To make these modifications, make an HTTP PUT request to /messages/{id} with any combination of the body parameters specified here.

The Nylas APIs expose a parsed and sanitized version of the original RFC-2822 email object, combined with state from the mail server, such as unread status and folder location. This results in a simple and universal object type that makes building applications a breeze.

We still provide access to the RFC-2822 raw message object if you want it.

Filtering, Pagination, and Views with Messages

The messages endpoint supports Filters, Pagination, and Views, making it easy to return a subset of messages in specific folder, from a certain address, with a specific subject, etc.

Message Filtering

Messages support various combinations of Filters. Check all the query parameters on the /messages endpoint for more information.

Message Pagination

By default the /messages endpoint will return a maximum of 100 objects. You should paginate through an entire user's mailbox by using the limit and offset URL query parameters. See Pagination for more details about pagination in general. Check all the query parameters on the /messages endpoint for more information.

Message Views

Messages support the use of Views by including the view query parameter in your request.

The expanded message view exposes several additional RFC2822 headers, useful for implementing custom threading or cross-mailbox identification. Pass the view=expanded query parameter when making requests to /messages and /messages/{id}

The following block is added to the message object when using the expanded view.

{
  "headers": {
    "In-Reply-To": "<evh5uy0shhpm5d0le89goor17-0@mailer.nylas.com>",
    "Message-Id": "<84umizq7c4jtrew491brpa6iu-0@mailer.nylas.com>",
    "References": ["<evh5uy0shhpm5d0le89goor17-0@mailer.nylas.com>"],
  }
}
Header Requirement Description
Message-Id optional Generated by clients while sending messages. It is different from a message's ID returned by the Nylas API (the message object's id). Unlike the id, the Message-Id header is not guaranteed to be unique since it is generated by clients. This field may be null.
In-Reply-To optional The parent Message-Id to which this message replied. Expected null for messages that are not replies.
References optional A list of Message-Ids related to a given message. Expected empty for messages which are not replies or related to existing messages.

A note about expanded message view

Note that these values are unrelated to Nylas object IDs. Because they are provided by clients without validation, there is no guarantee of their accuracy, uniqueness, or consistency.

Suggest Edits

/messages

 
gethttps://api.nylas.com/messages
curl --request GET \
  --url https://api.nylas.com/messages \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/messages',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/messages");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/messages"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

view
string

Can be one of ids, count, or expanded. See Views for more info.

limit
int32

Number of objects to return. Often defaults to 100. If set too high, requests may fail to prevent excessively large response bodies.

offset
int32

Zero-based offset from default object sorting. See pagination for more info.

subject
string

Return messages with a matching literal subject

any_email
string

Return messages that have been sent or received from this email address

to
string

Return messages sent to this email address

from
string

Return messages sent from this email address

cc
string

Return messages that were CC'd to this email address

bcc
string

Return messages that were BCC'd to this email address, likely sent from the parent account. (Most SMTP gateways remove BCC information.)

in
string

Return messages in a given folder, or with a given label. This parameter supports the name, display_name, or id of a folder or label. Note: If you'd like to get all drafts use the /drafts endpoint.

unread
boolean

Return unread messages

starred
boolean

Return starred messages

filename
string

Return messages that contain attachments with the given filename

thread_id
string

Return messages belonging to a specific thread.

received_before
string

Return messages received before this unix timestamp

received_after
string

Return messages received after this unix timestamp.

has_attachment
boolean

Returns only messages that have attachments (only true is supported)

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/messages/{id}

 
gethttps://api.nylas.com/messages/id
curl --request GET \
  --url https://api.nylas.com/messages/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/messages/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/messages/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/messages/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/messages/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The message_id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/messages/{id}

 
puthttps://api.nylas.com/messages/id
curl --request PUT \
  --url https://api.nylas.com/messages/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.nylas.com/messages/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/messages/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.nylas.com/messages/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/messages/id"

headers = {'authorization': 'Authorization'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The message_id

Body Params

unread
boolean

Set true to mark as unread, and false to mark as read

starred
boolean

Set trueto star, and false to un-star a message

folder_id
string

folder_id to move this message to

label_ids
string

label_ids to apply, overwriting all previous labels on the message.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Unread status

In most systems, incoming mail is given an "unread" status to help the user triage messages. When viewing a message, it's customary for a mail app to automatically modify this "unread" attribute and remove the notification or highlight.

However, unlike its literal meaning, the unread value is mutable, and so it's possible to manually change a message back to "unread." Users will often do this as a reminder to follow up or triage a message later.

The Nylas platform lets you easily change the unread property of a message. This change will propagate to the backend mailbox provider, such as Gmail or Exchange.

Starring (flags)

Stars, also know as "flags", are displayed in nearly every mail app, and are an easy way to highlight a specific message. Although most apps usually show stars at the thread level, they are actually an attribute of messages themselves. (e.g. If one message in a thread is starred, the entire thread is shown as starred.)

The starred property in the Nylas API is equivalent to stars in Gmail, the IMAP flagged message attribute and Microsoft Exchange message "flags."

They Nylas platform lets you easily change the starred property of a message. This change will propagate to the backend mailbox provider, such as Gmail or Exchange.

Moving a message

Note about moving messages

This is only supported for accounts where the organization_unit is set to folder. Generally this is all non-Gmail/Google Apps accounts. You can check if an account supports folders by the organization_unit property on the Account object.

Folders are a common way to organize email messages. A mailbox usually has a set of standard folders like Inbox, Sent Mail, and Trash, along with any number of user-created folders. For more information about types and capabilities, see the Folders section.

Nylas supports moving messages between folders with a single, simple API call. Note that messages can only exist within one folder.

Modifying labels

Note about modifying message labels

This is only supported for accounts where the organization_unit is set to label. Generally this is only Gmail/Google Apps accounts. You can check if an account supports labels by the organization_unit property on the Account object.

Labels are a Gmail-specific way of organizing messages. A message or thread can have multiple labels, enabling more complex queries and email management workflows.

The Nylas platform lets you easily change the labels associated with a message. This change will propagate to the backend mailbox provider (Gmail).

Suggest Edits

Raw message contents

Access to the RFC-2822 message object

 
gethttps://api.nylas.com/messages/id
curl --request GET \
  --url https://api.nylas.com/messages/id \
  --header 'accept: message/rfc822' \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/messages/id',
  headers: 
   { authorization: 'Authorization',
     accept: 'message/rfc822' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/messages/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["accept"] = 'message/rfc822'
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/messages/id");
xhr.setRequestHeader("accept", "message/rfc822");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/messages/id"

headers = {
    'accept': "message/rfc822",
    'authorization': "Authorization"
    }

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Delivered-To: ben.bitdiddle1861@gmail.com
Received: by 10.36.105.83 with SMTP id e80csp448398itc;
        Mon, 2 Mar 2015 22:32:19 -0800 (PST)
X-Received: by 10.140.146.6 with SMTP id 6mr57679712qhs.44.1425364337630;
        Mon, 02 Mar 2015 22:32:17 -0800 (PST)
Return-Path: <golang-nuts+bncBC35DTG33YGBB3NK2WTQKGQEPOXSM4Q@googlegroups.com>
Received: from mail-qg0-x23b.google.com (mail-qg0-x23b.google.com. [2607:f8b0:400d:c04::23b])

<<<Raw mime body starts here...>>

Path Params

id
string
required

The message_id

Headers

Accept
string
required
Authorization
string
required

access_token as HTTP Basic Auth username

 

If you need to access some specific email headers or data that is not exposed by the standard message API, you can request the original raw message data originally downloaded from the mail server. Setting the Accept header to message/rfc822 will return the entire raw message object in RFC 2822 format, including all MIME body subtypes and attachments.

Suggest Edits

Introduction

 

Folders behave like normal IMAP or filesystem folders. A Message can only exist within one folder at a time, but a Thread with many messages may span several folders.

Folders are only supported on accounts for which organization_unit is folder. You can check if an account supports labels by the organization_unit property on the Account object.

Folders support basic CRUD operations outlined in the endpoints below.

Using Filters with Folders

The endpoints for Messages, Threads, and Files support Filters for folders using the in query parameter. Simply pass a folder_id, name, or display_name value when calling those endpoints. This conveniently has the same format for both labels and folders, so you application can specify a single filtering request independent of organization unit. See the Filters documentation for more details.

Nested Folders

IMAP has very limited support for nested folders: it encodes a folder's path in its name. For example, the folder Accounting/Taxes will actually be named Accounting.Taxes or even INBOX.Accounting.Taxes depending on your IMAP server. To complicate things, different IMAP servers use different path separators (for example, Taxes.Accounting` on server A will beTaxes\Accounting` on server B).

The Nylas API handles nested IMAP folders transparently. Creating a Taxes/Invoices folder using the API will create a folder with the right path separators (i.e: depending on your server, INBOX.Taxes.Invoices or Taxes/Invoices).

Suggest Edits

/folders

 
gethttps://api.nylas.com/folders
curl --request GET \
  --url https://api.nylas.com/folders \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/folders',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/folders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/folders");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/folders"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "id": "4zv7pgvihjvuptbwv57kiz62",
        "object": "folder",
        "name": "inbox",
        "display_name": "INBOX",
        "account_id": "awa6ltos76vz5hvphkp8k17nt"
    },
    {
        "id": "76zrfd8ln5zo2swalu1yojhty",
        "name": "archive",
        "display_name": "2015 Archive",
        "account_id": "awa6ltos76vz5hvphkp8k17nt",
        "object": "folder"
    }
]

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "folder")
account_id string Reference to parent account object
name string Standard categories type, based on RFC-6154.
Can be one of the following:
  • inbox
  • all
  • trash
  • archive
  • drafts
  • sent
  • spam
  • important
  • null (regular user-created folder)
display_name string Localized name of folder, matching what is presented in their other mail apps. If you are displaying folders, use this instead of name.
Suggest Edits

/folders/{id}

 
gethttps://api.nylas.com/folders/id
curl --request GET \
  --url https://api.nylas.com/folders/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/folders/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/folders/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/folders/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/folders/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "4zv7pgvihjvuptbwv57kiz62",
  "object": "folder",
  "name": "inbox",
  "display_name": "INBOX",
  "account_id": "awa6ltos76vz5hvphkp8k17nt"
}

Path Params

id
string
required

The folder_id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/folders

 
posthttps://api.nylas.com/folders
curl --request POST \
  --url https://api.nylas.com/folders \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/folders',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/folders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/folders");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/folders"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "d121cvdyjhgacaqyymzjg5prl",
    "name": null,
    "display_name": "My New Folder",
    "account_id": "awa6ltos76vz5hvphkp8k17nt",
    "object": "folder"
}

Body Params

display_name
string

Human-readable name for the new folder

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

This endpoint will return a new folder object upon success. An error will be returned if the supplied display_name is too long, or a conflicting folder already exists.

Suggest Edits

/folders/{id}

 
puthttps://api.nylas.com/folders/id
curl --request PUT \
  --url https://api.nylas.com/folders/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.nylas.com/folders/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/folders/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.nylas.com/folders/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/folders/id"

headers = {'authorization': 'Authorization'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "id": "d121cvdyjhgacaqyymzjg5prl",
    "name": null,
    "display_name": "New Folder Name",
    "account_id": "awa6ltos76vz5hvphkp8k17nt",
    "object": "folder"
}

Path Params

id
string
required

The folder_id

Body Params

display_name
string

Human-readable name for the new folder

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

The display_name attribute of a folder can modified, and these changes will propagate back to the account provider. Note that the core folders such as INBOX, Trash, etc. often cannot be renamed.

A successful request will return the full updated folder object.

Suggest Edits

/folders/{id}

 
deletehttps://api.nylas.com/folders/id
curl --request DELETE \
  --url https://api.nylas.com/folders/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.nylas.com/folders/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/folders/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.nylas.com/folders/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/folders/id"

headers = {'authorization': 'Authorization'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The folder_id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Note about deleting folders

Folders must be emptied before being deleted to prevent the accidental deletion of threads. If the requested folder is not empty, the server will respond with a Forbidden error.

Suggest Edits

Introduction

 

Labels are equivalent to Gmail labels. Messages can have more than one label, which is popular for users who set up mail filters.

Labels are only supported on accounts for which organization_unit is label. You can check if an account supports labels by the organization_unit property on the Account object.

Labels support basic CRUD operations outlined in the endpoints below.

Using Filters with Labels

The endpoints for Messages, Threads, and Files support Filters for labels using the in query parameter. Simply pass a label id, name, or display_name value when calling those endpoints. This conveniently has the same format for both labels and folders, so you application can specify a single filtering request independent of organization unit. See the Filters documentation for more details.

Suggest Edits

/labels

 
gethttps://api.nylas.com/labels
curl --request GET \
  --url https://api.nylas.com/labels \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/labels',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/labels");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/labels"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "label")
account_id string Reference to parent account object
name string Standard categories type, based on RFC-6154.
Can be one of the following:
  • inbox
  • all
  • trash
  • archive
  • drafts
  • sent
  • spam
  • important
  • null (regular user-created label)
display_name string Localized name of label, matching what is presented in their other mail apps. If you are displaying labels, use this instead of name.
Suggest Edits

/labels/{id}

 
gethttps://api.nylas.com/labels/id
curl --request GET \
  --url https://api.nylas.com/labels/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/labels/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/labels/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/labels/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/labels/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "display_name": "homework",
  "id": "56po63srws43nht7owyt5knz4",
  "name": null,
  "account_id": "awa6ltos76vz5hvphkp8k17nt",
  "object": "label"
}

Path Params

id
string
required

The label id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/labels

 
posthttps://api.nylas.com/labels
curl --request POST \
  --url https://api.nylas.com/labels \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/labels',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/labels");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/labels"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "d121cvdyjhgacaqyymzjg5prl",
  "name": null,
  "display_name": "My New Label",
  "account_id": "awa6ltos76vz5hvphkp8k17nt",
  "object": "label"
}

Body Params

display_name
string
required

Human-readable name for the new label

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

You can easily create new labels on accounts where the organization_unit is set to label. Generally this is only Gmail/Google Apps accounts.

This endpoint will return a new label object upon success. An error will be returned if the supplied display_name is too long, or a conflicting label already exists.

Suggest Edits

/labels/{id}

 
puthttps://api.nylas.com/labels
curl --request PUT \
  --url https://api.nylas.com/labels \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.nylas.com/labels',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.nylas.com/labels");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/labels"

headers = {'authorization': 'Authorization'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "d121cvdyjhgacaqyymzjg5prl",
  "name": null,
  "display_name": "My New Label",
  "account_id": "awa6ltos76vz5hvphkp8k17nt",
  "object": "label"
}

Path Params

id
string
required

The label id

Body Params

display_name
string
required

Human-readable name for the new label

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

The display_name attribute of a label can modified, and these changes will propagate back to the account provider. Note that the core labels such as Inbox, Trash, etc. cannot be renamed.

A successful request will return the full updated label object.

Suggest Edits

/labels/{id}

 
deletehttps://api.nylas.com/labels
curl --request DELETE \
  --url https://api.nylas.com/labels \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.nylas.com/labels',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/labels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.nylas.com/labels");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/labels"

headers = {'authorization': 'Authorization'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "id": "d121cvdyjhgacaqyymzjg5prl",
  "name": null,
  "display_name": "My New Label",
  "account_id": "awa6ltos76vz5hvphkp8k17nt",
  "object": "label"
}

Path Params

id
string
required

The label id

Body Params

display_name
string
required

Human-readable name for the new label

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Labels can be deleted by issuing a DELETE request to the label’s URI. A label can be deleted even if it still has associated messages.

Suggest Edits

Introduction

 

A draft is a special kind of message which has not been sent, and therefore its body contents and recipients are still mutable. The drafts endpoints let you read and modify existing drafts, create new drafts, send drafts, and delete drafts. Draft modifications are propagated to the mailbox provider in all cases, excluding Microsoft Exchange systems.

Suggest Edits

/drafts

 
gethttps://api.nylas.com/drafts
curl --request GET \
  --url https://api.nylas.com/drafts \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/drafts',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/drafts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/drafts");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/drafts"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "draft")
account_id string Reference to parent account object
thread_id string Reference to parent thread object. If this is a new draft, the thread will be empty.
subject string Subject line of the draft
reply_to_message_id string ID of a message this draft is a reply to, allowing the sending API to include threading-specific headers for other mail clients
from array Array containing a single name+email pair to set as the "from" header. (See "Aliases" below.)
reply_to array Array of name+email pairs to set an alternative Reply-To header in the final sent message
to array Array of name+email pairs of recipients
cc array Array of name+email pairs of recipients to be cc'd
bcc array Array of name+email pairs of recipients to be bcc'd
date unix timestamp Timestamp of the last modification of the draft
unread boolean Believe it or not, drafts also have an unread state
starred boolean Starred or flagged state (mutable)
snippet string A shortened plain-text preview of the draft body
body string The full HTML draft body text
files array Array of file objects, if draft includes attachments
events array Array event objects, if draft includes calendar invites
folder folder object A single folder object indicating the location of the draft, present only if the parent account's organization_unit is folder. Customarily this is a folder where name is drafts, but not always.
labels array An list of label objects, present only if the parent account's organization_unit is "label". These have Gmail-style semantics and can be arbitrarily added and removed from messages.
version integer Incrementing value related to draft updates.
You can use this to compare revisions, or invalidate your local cache.
Suggest Edits

/drafts/{id}

 
gethttps://api.nylas.com/drafts/id
curl --request GET \
  --url https://api.nylas.com/drafts/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/drafts/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/drafts/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/drafts/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/drafts/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The draft id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/drafts

 
posthttps://api.nylas.com/drafts
curl --request POST \
  --url https://api.nylas.com/drafts \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/drafts',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/drafts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/drafts");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/drafts"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

subject
string

Subject line of the draft

to
array of objects

Name and email pairs of recipients

name
email
cc
array of objects

Name and email pairs of recipients to be cc’d

name
email
bcc
array of objects

Name and email pairs of recipients to be bcc’d

name
email
from
array of objects

Array containing a single name and email pair to set as the “from” header. (See “Aliases” below.) Note that not all providers support setting this in a draft.

name
email
reply_to
array of objects

Array of name and email pairs to set an alternative Reply-To header in the final sent message. Note that not all providers support setting this in a draft.

name
email
body
string

The full HTML draft body text

file_ids
array of strings

Array of file IDs, if draft includes attachments. Note that creating a draft will fail if these files have not yet been uploaded.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Note about creating drafts

All body params optional though if omitted, an empty draft will still be created. A successful response will contain the newly created draft object. At least one recipient in to, cc, or bcc must be specified before sending.

Attachments

Creating a draft will fail if the files with the referenced file_ids have not been uploaded. See Files for more details on how to upload and reference attachments.

Replies

If the draft is a response to an existing message, you should provide the message's ID as a reply_to_message_id attribute and omit the subject parameter. Note that you still must explicitly specify the message's recipients in the to, cc or bcc fields of the post body. (This is by design to prevent any ambiguity about whom the message will be sent to.)

Aliases

If you would like to use an alias for sending and/or receiving emails, you can optionally set the from or reply_to fields. Note that if the given address is actually not an alias, most SMTP servers will either reject the message or silently replace it with the primary sending address.

If the from and reply_to fields are omitted, the account's default sending name and address will be used.

Suggest Edits

/drafts/{id}

 
puthttps://api.nylas.com/drafts/id
curl --request PUT \
  --url https://api.nylas.com/drafts/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.nylas.com/drafts/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/drafts/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.nylas.com/drafts/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/drafts/id"

headers = {'authorization': 'Authorization'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The draft id

Body Params

subject
string

Subject line of the draft

to
array of strings

Name and email pairs of recipients

cc
array of strings

Name and email pairs of recipients to be cc’d

bcc
array of strings

Name and email pairs of recipients to be bcc’d

from
array of strings

Array containing a single name and email pair to set as the “from” header. (See “Aliases” below.) Note that not all providers support setting this in a draft.

reply_to
array of strings

Array of name and email pairs to set an alternative Reply-To header in the final sent message. Note that not all providers support setting this in a draft.

body
string

The full HTML draft body text

file_ids
array of strings

Array of file IDs, if draft includes attachments. Note that creating a draft will fail if these files have not yet been uploaded.

version
string
required

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

The request body must contain the version of the draft you wish to update. Other fields are optional and will overwrite previous values.

Updating a draft returns a draft object with the same id but different version. When submitting subsequent send or save actions, you must use this new version.

Suggest Edits

/drafts/{id}

 
deletehttps://api.nylas.com/drafts/id
curl --request DELETE \
  --url https://api.nylas.com/drafts/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.nylas.com/drafts/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/drafts/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.nylas.com/drafts/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/drafts/id"

headers = {'authorization': 'Authorization'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The draft id

Body Params

version
string
required

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Drafts can be deleting by issuing a DELETE request to the draft’s URI. The request body must contain a JSON object specifying the latest version, or deletion will fail. This is to prevent accidental deletion of drafts which have been updated.

Suggest Edits

Introduction

 

The Nylas platform provides two ways to send messages: either through sending an existing draft, or by sending directly. Both systems send mail through the account's original SMTP/ActiveSync gateway, just as if they were sent using any other app. This means messages sent through Nylas have very high deliverability (i.e. not landing in Gmail's promotions tab), but may also be subject to backend provider rate-limiting and abuse detection. Make sure to send wisely!

Sending timeouts

A successful request to the send endpoint can sometimes take up to two minutes for self-hosted Exchange accounts, though the average send time is around 2 seconds. We recommend that you set a minimum timeout of 150s to ensure that you receive a response from us.

All sending operations are synchronous, meaning the request will block until the draft has succeeded or failed. In the event of failure, the sending API will not automatically retry.

We recommend that you apply backoff when HTTP 503s are returned. Your app may need to wait 10-20 minutes, or SMTP servers may continue to refuse connections for a particular account. For some providers like Gmail, there are hard limits on the number of messages you can send per day.

If large-volume sending continues to fail for your application, we recommend switching to a transactional sending service like Mailgun, Sendgrid, Mandrill, or Amazon SES.

Sending Errors

Sometimes message delivery can fail if the user’s email gateway rejects the message. This could happen for a number of reasons, including illegal attachment data, bad credentials, or rate limiting. If your message is sent successfully, the server will respond with an HTTP response code of 200 OK. If your message couldn’t be sent, the server will respond with an appropriate error code.

Status Code Reason
200 OK Your message was sent.
400 Bad Request Your request was malformed, or contained an invalid parameter. The most common issue is invalid JSON.
402 Message Rejected The mail provider rejected your message because of its content or recipients. Note this means that your message may have been delivered to only a subset of participants if the message includes "Sending to at least one recipient failed".
403 Unauthorized The server was unable to authenticate with the user's mail provider. Re-authenticate the user and try again.
422 Mail provider error An error occurred while the mail provider was sending the message. See the server_error in the response body JSON for more information.
429 Quota Exceeded The user has exceeded their mail provider's sending quota. Unfortunately there is no reliable way to determine these limits. Wait and try again later.
503 Service Unavailable There was an error connecting to the user's mail provider. Wait and try again.

In addition, the response body contains a JSON object with information about the specific error, including the following attributes:

Status Code Type Reason
type string Error type
message string A brief human-readable description of the error.
server_error string (optional) The original error returned by the user's mail server.

See Errors for more information about error responses and how to handle them.

Sending inline images

You can send image attachments inline in the body of your emails. Simply reference one of the attached file_ids in an img tag. For example, if one of your attachments has file_id = '472ypl5vqbnh0l2ac3y71cdks' then you could display it inline like in the example to the right. Don't forget to prepend the file_id with cid: for the src attribute.

<div>
  <p>Before image</p>
  	<img src="cid:472ypl5vqbnh0l2ac3y71cdks">
  <p>After image</p>
</div>

Setting the sender's name

Some mail servers allow you to set the sender name when sending mail. Nylas will pass along the default name stored on the /account automatically. You can also override this default name each time you send an email by passing a from parameter. See Sending directly for more info.

Sender name support

Not every mail server will respect this value. You might run into an issue where you set the "From" name but the message that is sent doesn't have that value. You might need to reach out to your mail provider to see what default name they use, and if they support overriding this default name.

Suggest Edits

Sending drafts

 
posthttps://api.nylas.com/send
curl --request POST \
  --url https://api.nylas.com/send \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/send',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/send");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/send"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

draft_id
string
required

id of existing draft

version
int32
required

Version of the draft. Must be most recent or the request will fail.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

Sending directly

Messages can be sent directly, without saving them as drafts beforehand.

 
posthttps://api.nylas.com/send
curl --request POST \
  --url https://api.nylas.com/send \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/send',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/send");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/send"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

subject
string

Subject line of the messages

reply_to_message_id
int32

ID of a message this draft is a reply to, allowing the sending API to include threading-specific headers for other mail clients

from
array of objects

Array containing a single name and email pair to set as the "from" header

name
email
reply_to
array of objects

Array of name+email pairs to set an alternative Reply-To header in the final sent message

name
email
to
array of objects

Array of name+email pairs of recipients

name
email
cc
array of objects

Array of name+email pairs of recipients to be cc’d

name
email
bcc
array of objects

Array of name+email pairs of recipients to be bcc’d

name
email
body
string

The full HTML body to send. If replying to a message, you should include quoted text here.

file_ids
array of strings

Array of File ids, if you are including attachments. Note that sending will fail if these files have not yet been uploaded.

tracking
object

Optional object that allows you to enable message tracking features for this message or thread.

 

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

A note on sending directly

All of these attributes are individually optional. However, sending a message will fail if there is no recipient specified in either to, cc, or bcc.

A successful response will include a full new Message object.

Suggest Edits

Sending raw MIME

 
posthttps://api.nylas.com/send
curl -X POST https://ACCESS_TOKEN@api.nylas.com/send -H "Content-Type: message/rfc822" -d 'MIME-Version: 1.0
  Content-Type: text/plain; charset=UTF-8
  In-Reply-To: <84umizq7c4jtrew491brpa6iu-0@mailer.nylas.com>
  References: <84umizq7c4jtrew491brpa6iu-0@mailer.nylas.com>
  Subject: Meeting on Thursday
  From: Bill <wbrogers@mit.edu>
  To: Ben Bitdiddle <ben.bitdiddle@gmail.com>

  Hey Ben,

  Would you like to grab coffee @ 2pm this Thursday?"
  Bill
  '
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

Content-Type
string
required
 

You can also send via submitting raw MIME message object. The submitted object is entirely preserved, except the bcc header which is removed. Additional headers used by Nylas may be added.

If the message is in reply to an existing message, you should make sure to include the In-Reply-To and References headers. These headers are set to the Message-Id header of the message you are replying to and Message-Id header of related messages, respectively. For more details, see this excellent article by djb.

A successful response will include a full new Message object.

Suggest Edits

Introduction

 

The files endpoint manages data attached to messages. It allows you to download existing attachments from messages and threads, as well as upload new files to be sent. Note that before creating or modifying a draft to include an attachment, you must upload it via this API and use the returned file ID.

Actual attached files may be relatively large (upwards of 25MB), so this API has separate endpoints for requesting file Metadata and Downloading the actual file.

Files can be downloaded by appending /download to the file metadata URI. If available, the response will include the filename in the Content-Disposition header.

The Upload endpoint is used to transfer files to Nylas, which must be done before adding them to a draft message. Data should be sent as multipart-form data with a single field named file.

Filtering and Files

This endpoint supports Filters and Pagination, which allow you to fetch multiple files matching specific criteria and iterate through a large set of files. See the query parameters in the endpoints below to see what kind of filtering is supported.

Popular Content-Type values corresponding to popular file extensions

Document Content-Type
PNG images image/png
JPEG images image/jpeg
PDF documents application/pdf
ZIP archives application/zip
MS Word (.doc) application/msword
MS Excel (.xls) application/vnd.ms-excel
MS Powerpoint (.ppt) application/vnd.ms-powerpoint
MS Word (.docx) application/vnd.openxmlformats-officedocument.wordprocessingml.document
Microsoft Powerpoint (.pptx) application/vnd.openxmlformats-officedocument.presentationml.pesentation
Microsoft Excel (.xlsx) application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

Here is a more complete list of Content Types.

Suggest Edits

/files

Access to file metadata

 
gethttps://api.nylas.com/files
curl --request GET \
  --url https://api.nylas.com/files \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/files',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/files");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/files"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

filename
string

Filter by the filename

message_id
string

Filter files by a message_id

content_type
string

Filter files by a content_type

view
string

Can be one of count or ids. See Views for more info.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "file")
account_id string Reference to parent account object
filename string Name of the file, if available
size integer Size of the file, in bytes
content_type string Content-Type of the file, sometimes also called Internet media type or MIME type.
message_ids array Array of identifiers for messages that contain this attachment. (Not guaranteed to be a complete set)
content_id string The Content-Id of the file. Sometimes this value will be empty. Using this value, your app can locate the associated cid URL in the message body and embed the resource inline.
Suggest Edits

/files/{id}

Access to file metadata

 
gethttps://api.nylas.com/files/id
curl --request GET \
  --url https://api.nylas.com/files/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/files/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/files/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/files/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/files/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The file id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/files/{id}/download

Download the actual file

 
gethttps://api.nylas.com/files/id/download
curl --request GET \
  --url https://api.nylas.com/files/id/download \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/files/id/download',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/files/id/download")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/files/id/download");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/files/id/download"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The file id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/files

Uploading files

 
posthttps://api.nylas.com/files
curl --request POST \
  --url https://api.nylas.com/files \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/files',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/files")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/files");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/files"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "content_type": "image/jpeg",
        "filename": "2015-08-08 15.15.29.jpg",
        "id": "3qfe4k3siosfjtjpfdnon8zbn",
        "account_id": "6aakaxzi4j5gn6f7kbb9e0fxs",
        "object": "file",
        "size": 762878
    }
]

Body Params

file
file
required

The file

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

This endpoint is used to transfer files to Nylas, which must be done before adding them to a draft message. Data should be sent as multipart-form data with a single field named file.

A successful upload will return an array with a single file object. This object's ID may be attached to a Draft by appending it to file_ids array of the draft object. Additionally, if the object is an image it may be included inline in the body of the email by referencing it inside an img tag like so: <img src="cid:file_id">. See Sending for more info about inline images.

Suggest Edits

/files/{id}

Delete files

 
deletehttps://api.nylas.com/files/id
curl --request DELETE \
  --url https://api.nylas.com/files/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.nylas.com/files/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/files/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.nylas.com/files/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/files/id"

headers = {'authorization': 'Authorization'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
null
{
    "message": "Can't delete file that is attachment.",
    "type": "invalid_request_error"
}

Path Params

id
string
required

The file id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

A successful deletion will return null along with a 200 OK response code.

Note

You can only delete files that have been uploaded directly to the API, and not files that have been generated from message attachments.

Suggest Edits

Introduction

 

Each account connected to Nylas can have zero or more calendars, and each calendar has a collection of individual events. The calendar object is very simple, and mostly serves as a container for events. The read_only flag on a calendar indicates whether or not you can modify its properties or make changes to its events.

The calendar endpoint supports Pagination (although most users have only a few calendars) and Views.

Provider-backed calendars

The primary calendar of the account is usually named the same as the email address, or sometimes simply called "Calendar." Users may also have other custom calendars, or access to shared team calendars. See Events for more details.

Events can be viewed, added, modified, and deleted on calendars where read_only is false. Changes are automatically synced back to the provider.

The "Emailed events" calendar

All accounts also include a special calendar called "Emailed events" which contains event invitations that have been sent to the user's mailbox. This calendar is read-only, meaning events cannot be added, updated, or deleted. However, the events can be RSVP'd to. See the Events documentation for details.

Suggest Edits

/calendars

 
gethttps://api.nylas.com/calendars
curl --request GET \
  --url https://api.nylas.com/calendars \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/calendars',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/calendars")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/calendars");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/calendars"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "description": null,
        "id": "67qmz3fuk9wfljwj1w8ngshkc",
        "name": "Calendar",
        "account_id": "bh1vu31mw9ap7ri5k166ah9uo",
        "object": "calendar",
        "read_only": false
    },
    {
        "description": "Emailed events",
        "id": "b4xm1jjibrxkymq81dbgeul8",
        "name": "Emailed events",
        "account_id": "bh1vu31mw9ap7ri5k166ah9uo",
        "object": "calendar",
        "read_only": true
    }
]

Query Params

view
string

Can be count or ids. See Views for more info.

limit
string

Limit the number of results returned. See Pagination for details.

offset
string

Set the offset for paginating results. See Pagination for details.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "file")
account_id string Reference to parent account object
name string Name of the Calendar
description string Description of the Calendar
read_only boolean True if the Calendar is read only
Suggest Edits

/calendars/{id}

 
gethttps://api.nylas.com/calendars/id
curl --request GET \
  --url https://api.nylas.com/calendars/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/calendars/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/calendars/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/calendars/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/calendars/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "description": null,
  "id": "67qmz3fuk9wfljwj1w8ngshkc",
  "name": "Calendar",
  "account_id": "bh1vu31mw9ap7ri5k166ah9uo",
  "object": "calendar",
  "read_only": false
}

Path Params

id
string
required

The calendar id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

Introduction

 

Events are objects within a calendar, generally supporting all features of modern scheduling apps. Using the calendar APIs, your application can schedule events, send meeting invitations, RSVP, and more.

Events supports Filtering and Pagination

The events endpoint supports filters, which allow you to fetch multiple events matching specific criteria, as well as pagination. See the Events endpoint query parameters for specific query parameters you can use to filter Events.

Event subobjects

There are various subobjects within the Event object itself. To learn more about each of these subobjects see Event Subobjects

Recurring events

Creating, updating and deleting recurring events is available for only Google Calendars at this time. Please note that updating or deleting a recurring event will impact ALL instances of the event. Any individual modifications (overrides), such as a one-off time change, will be updated or deleted as well.

Using the expand_recurring URL parameter is an easy way to expand recurring events server-side so your application doesn't need to deal with RRULEs. Note that when using this query parameter, you must also use filters to specify a time range.

Currently, these expanded instances of recurring events are read-only for non-Google Calendars. For Google Calendars, however, we support update and delete operations.

If the recurring event has overrides, we will return these as individual events regardless of whether expand_recurring is set or not.

If expand_recurring is not set, we will return any one-off cancellations in addition to the base event, for apps that are expanding the recurrence client-side. A cancellation has the field cancelled set to true.

Suggest Edits

/events

 
gethttps://api.nylas.com/events
curl --request GET \
  --url https://api.nylas.com/events \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/events',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/events");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/events"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

expand_recurring
boolean

If set to true, expands single recurring events into individual event instances that fall within the requested time range.

show_cancelled
boolean

If set to true, also return cancelled events. (false by default)

limit
int32

Number of objects to return. Often defaults to 100. If set too high, requests may fail to prevent excessively large response bodies. See Pagination for more info.

offset
int32

Zero-based offset from default object sorting. See Pagination for more info.

event_id
string

Return the event with the given id

calendar_id
string

Return events belonging to the referenced calendar

title
string

Return events whose title matches the provided value.

description
string

Return events whose description matches the provided value.

location
string

Return events whose location matches the provided value.

starts_before
int32

Return events that start before this unix timestamp.

starts_after
int32

Return events that start after this unix timestamp.

ends_before
int32

Return events that end before this unix timestamp.

ends_after
int32

Return events that end after this unix timestamp.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Note about event sorting

Events are always sorted by their start date.

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "event")
account_id string Reference to parent account object
calendar_id string Reference to the parent calendar object
title string Title of the event, usually kept short.
description string Description of the event, which may contain more details or an agenda.
when subobject One of four subobjects corresponding to the time and duration of an event: time, timespan, date, or datespan. See below for more details.
location string Location, such as a physical address or meeting room name
owner string The owner of the event, usually their email or name and email.
participants array Array of others invited to the event. Keys are email, name, status. Participants may also be rooms or resources. See below for more details.
status string Either confirmed, tentative, or cancelled.
read_only boolean Whether the event can be modified
busy boolean On shared or public calendars, whether to show this event's time block as available or not. (Also called "transparency" in some systems.)
recurrence subobject Included if the event is a master recurring event. See below for the subobject definition
master_event_id string Only included in exceptions (overrides) to recurring events, the id of the recurring event.
original_start_time unix timestamp Only included in exceptions (overrides) to recurring events, the start time of the recurring event.
Suggest Edits

/events/{id}

 
gethttps://api.nylas.com/events/id
curl --request GET \
  --url https://api.nylas.com/events/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/events/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/events/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/events/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/events/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "object": "event",
    "id": "4ee4xbnx7pxdb9g7c2f8ncyto",
    "calendar_id": "ci0k1wfyv533ccgox4t7uri4h",
    "account_id": "14e5bn96uizyuhidhcw5rfrb0",
    "description": null,
    "location": null,
    "owner": "Ben Bitdiddle <example@gmail.com>",
    "participants": [
        {
            "email": "example@gmail.com",
            "name": "Ben Bitdiddle",
            "status": "yes"
        }
    ],
    "read_only": false,
    "title": "Meeting with Ben Bitdiddle",
    "when": {
        "object": "timespan",
        "end_time": 1408123800,
        "start_time": 1408120200
    },
    "busy": true,
    "status": "confirmed"
}

Path Params

id
string
required

The event id

Query Params

expand_recurring
boolean

If set to true, expands single recurring events into individual event instances that fall within the requested time range.

show_cancelled
boolean

If set to true, also return cancelled events. (false by default)

limit
int32

Number of objects to return. Often defaults to 100. If set too high, requests may fail to prevent excessively large response bodies. See Pagination for more info.

offset
int32

Zero-based offset from default object sorting. See Pagination for more info.

event_id
string

Return the event with the given id

calendar_id
string

Return events belonging to the referenced calendar

title
string

Return events whose title matches the provided value.

description
string

Return events whose description matches the provided value.

location
string

Return events whose location matches the provided value.

starts_before
int32

Return events that start before this unix timestamp.

starts_after
int32

Return events that start after this unix timestamp.

ends_before
int32

Return events that end before this unix timestamp.

ends_after
int32

Return events that end after this unix timestamp.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

/events

 
posthttps://api.nylas.com/events
curl --request POST \
  --url https://api.nylas.com/events \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/events',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/events");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/events"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

notify_participants
boolean

If set to true, email notifications containing the calendar event will be sent to all event participants.

Body Params

calendar_id
string
required

The calendar_id of the Calendar this event should be added to.

when
mixed type
required

One of four subobjects corresponding to the time and duration of an event: Time, Timespan, Date, or Datespan.

title
string

Title of the event, usually kept short.

description
string

Description of the event, which may contain more details or an agenda.

location
string

Location, such as a physical address or meeting room name

participants
array of objects

Array of Participant subobjects.

email
status
name
comment
busy
boolean

On shared or public calendars, whether to show this event’s time block as available or not. (Also called “transparency” in some systems.)

recurrence
mixed type

Recurrence subobject specifying future occurrences.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Note about event sorting

Events are always sorted by their start date.

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute Type Description
id string Globally unique object identifier
object string A string describing the type of object (value is "event")
account_id string Reference to parent account object
calendar_id string Reference to the parent calendar object
title string Title of the event, usually kept short.
description string Description of the event, which may contain more details or an agenda.
when subobject One of four subobjects corresponding to the time and duration of an event: time, timespan, date, or datespan. See below for more details.
location string Location, such as a physical address or meeting room name
owner string The owner of the event, usually their email or name and email.
participants array Array of others invited to the event. Keys are email, name, status. Participants may also be rooms or resources. See below for more details.
status string Either confirmed, tentative, or cancelled.
read_only boolean Whether the event can be modified
busy boolean On shared or public calendars, whether to show this event's time block as available or not. (Also called "transparency" in some systems.)
recurrence subobject Included if the event is a master recurring event. See below for the subobject definition
master_event_id string Only included in exceptions (overrides) to recurring events, the id of the recurring event.
original_start_time unix timestamp Only included in exceptions (overrides) to recurring events, the start time of the recurring event.
Suggest Edits

/events/{id}

 
puthttps://api.nylas.com/events/id
curl --request PUT \
  --url https://api.nylas.com/events/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.nylas.com/events/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/events/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.nylas.com/events/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/events/id"

headers = {'authorization': 'Authorization'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The event id to update

Query Params

notify_participants
boolean

If set to true, email notifications containing the calendar event will be sent to all event participants.

Body Params

when
mixed type

One of four subobjects corresponding to the time and duration of an event: Time, Timespan, Date, or Datespan.

title
string

Title of the event, usually kept short.

description
string

Description of the event, which may contain more details or an agenda.

location
string

Location, such as a physical address or meeting room name

participants
array of objects

Array of Participant subobjects.

email
status
name
comment
busy
boolean

On shared or public calendars, whether to show this event’s time block as available or not. (Also called “transparency” in some systems.)

recurrence
mixed type

Recurrence subobject specifying future occurrences.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Note about read_only and recurring event updates

Updating and deleting an event is managed in a similar fashion to other endpoints with the restriction that read_only events cannot be updated and events cannot be updated or deleted from a read_only calendar.

Furthermore, updates cannot be made to recurring events yet.

Suggest Edits

/events/{id}

 
deletehttps://api.nylas.com/events/id
curl --request DELETE \
  --url https://api.nylas.com/events/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.nylas.com/events/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/events/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.nylas.com/events/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/events/id"

headers = {'authorization': 'Authorization'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The event id to update

Query Params

notify_participants
boolean

If set to true, email notifications containing the calendar event will be sent to all event participants.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Events can also be deleted from the calendar. Pass the notify_participants URL parameter to notify those who have been invited that the event has been cancelled.

Suggest Edits

Event Subobjects

 

The Event object has various subobjects that are detailed below.

A note about the `object` attribute

For each of the following event sub-objects, you might notice an object attribute. This is an attribute that is only returned by the Nylas API to easily indicate the type of subobject. You should not send this object attribute when submitting POST requests to the /event endpoint.

Participants

The participants attribute is returned as an array of dictionaries corresponding to participants. These include the keys:

Attribute Type Description
name string The participant's full name (optional)
email string The participant's email address
status string Attendance status. Allowed values are yes, maybe, no and noreply. Defaults is noreply
comment string A comment by the participant (optional) 
"participants": [
  {
    "comment": null,
    "email": "kelly@nylas.com",
    "name": "Kelly Nylanaut",
    "status": "noreply"
  },
  {
    "comment": null,
    "email": "sarah@nylas.com",
    "name": "Sarah Nylanaut",
    "status": "no"
  }
]

Time

The time subobject corresponds a single moment in time, which has no duration. Reminders or alarms would be represented as time subobjects.

Attribute Type Description
object string A string describing the type of object (value is "time"). Do not submit this value in POST requests. This is a read-only attribute that Nylas API returns to help you detect the type of event subobject.
time unix timestamp A UNIX timestamp (UTC) 
{
"object": "time",
"time": 1408875644
}

Timespan

A span of time with a specific beginning and end time. An hour lunch meeting would be represented as timespan subobjects.

Attribute Type Description
object string A string describing the type of object (value is "timespan"). Do not submit this value in POST requests. This is a read-only attribute that Nylas API returns to help you detect the type of event subobject.
start_time unix timestamp Starting time of the event
end_time unix timestamp Ending time of the event 
{
  "object": "timespan",
  "start_time": 1409594400,
  "end_time": 1409598000
}

Date

A specific date for an event, without a clock-based starting or end time. Your birthday and holidays would be represented as date subobjects.

Attribute Type Description
object string A string describing the type of object (value is "date"). Do not submit this value in POST requests. This is a read-only attribute that Nylas API returns to help you detect the type of event subobject.
date date Date of occurance in ISO 8601 format. 
{
  "object": "date",
  "date": "1912-06-23"
}

Datespan

A span of entire days without specific times. A business quarter or academic semester would be represented as datespan subobjects.

Attribute Type Description
object string A string describing the type of object (value is "datespan"). Do not submit this value in POST requests. This is a read-only attribute that Nylas API returns to help you detect the type of event subobject.
start_date date Start date in ISO 8601 format.
end_date date End date in ISO 8601 format. 
{
  "object": "datespan",
  "start_date": "1815-12-10",
  "end_date": "1852-11-27"
}

Recurrence

If requesting events without expand_recurring, the events endpoint will only return the 'master' recurring event and only if it falls within the requested time range. The recurrence attribute contains recurrence info in RRULE form; this tool is helpful in understanding the RRULE spec.

Attribute Type Description
timezone string IANA time zone database formatted string (e.g. America/New_York)
rrule array Array of RRULE and EXDATE strings. See RFC-5545 for more details. Please note that EXRULE and RDATE strings aren't supported for POST or PUT requests at this time. 
"recurrence": {
  "rrule": [
    "RRULE:FREQ=WEEKLY;BYDAY=MO"
  ],
  "timezone": "America/New_York"
},
Suggest Edits

RSVPing to invitations

The RSVP endpoint allows you to send attendance status updates to event organizers. Note this is only possible for events that appears on the “Emailed events”, which are calendar invitations.

 
posthttps://api.nylas.com/send-rsvp
curl --request POST \
  --url https://api.nylas.com/send-rsvp \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/send-rsvp',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/send-rsvp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/send-rsvp");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/send-rsvp"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

notify_participants
boolean

If set to true, email notifications containing the calendar event will be sent to all event participants.

Body Params

event_id
string
required

Which event you are RSVPing to. Must be a valid event ID from the “Emailed events” calendar.

status
string
required

Can be one of yes, no, or maybe

account_id
string
required

Reference to parent Account object.

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

If the RSVP is successful, the event object is returned with your RSVP participant status updated. This endpoint is idempotent: this means that only one email will be sent when you issue the same request with the same body multiple times.

RSVP Errors

Behind the scenes, RSVPs work by sending an email back to the event organizer in iMIP format. Therefore, errors when RSVPing to events follow the same status codes as sending errors.

Suggest Edits

Introduction

 

The Nylas APIs provide access to the user's contacts, making it easy to add contact autocomplete, address book integration, and more to your application.

Version 2.0 only

Our contacts support got a major upgrade in v2.0 of the API. This section pertains to the functionality in v2.0 of the API. If you haven't upgraded your API version yet, check out the API Versioning section.

Contacts supports Filtering and Pagination

The contacts endpoint supports filters, which allow you to fetch multiple contacts matching specific criteria, as well as pagination. See the Contacts endpoint query parameters for specific query parameters you can use to filter Contacts.

The Contact Object

Responses are encoded as UTF-8 JSON objects with the following attributes:

Attribute
Type
Description

id

string

Globally unique object identifier

object

string

A string describing the type of object (value is "contact")

account_id

string

Reference to parent account object

given_name

string

Given name of the contact

middle_name

string

Middle name of the contact

surname

string

Surname of the contact

suffix

string

Suffix (e.g. Jr., Sr., III)

nickname

string

Nickname of the contact

birthday

string

Birthday of contact in the form YYYY-MM-DD

company_name

string

Name of the company the contact works for

job_title

string

Job title of the contact

manager_name

string

Name of the manager of the contact

office_location

string

Location of the office of the contact - this is a free-form field

notes

string

Notes about the contact

picture_url

string

The URL to endpoint for the contact picture - see GET /contacts/<id>/picture for more details

emails

List[Email]

A list of email address objects - see Email for more details

im_addresses

List[IMAddress]

A list of Instant Messaging (IM) Address objects - see IM Address for more details

physical_addresses

List[PhysicalAddress]

A list of physical address objects - see Physical Address for more details

phone_numbers

List[PhoneNumber]

A list of phone number objects -see Phone Number for more details

web_pages

List[WebPage]

A list of web page objects - see Web Page for more details

A few of the fields on the contact model have lists values. These are lists of different objects: Email, IM Address, Physical Address, Phone Number and Web Page.

Email

Attribute
Type
Description

type

string

Type of the email address. Could be work or personal.

email

string

The email address. This is a free-form string.

Instant Messenger (IM) Address

Attribute
Type
Description

type

string

Type of the IM address. Could be gtalk, aim, yahoo, lync, skype, qq, msn, icq, jabber.

im_address

string

The IM address. This is a free-form string.

Physical Address

Attribute
Type
Description

format

string

Format of the address. Could be structured or unstructured. Right now, only structured addresses are supported.

type

string

The type of the address. Could be work or home or other.

street_address

string

The street address which includes house number and street name.

city

string

The city of the address.

postal_code

string

The postal code of the address.

state

string

The state of the address. This can be a full name or the state abbreviation.

country

string

The country of the address. This can be a full name or the country abbreviation.

Phone Number

Attribute
Type
Description

type

string

Type of the phone number. Could be business, home, mobile, pager, business_fax, home_fax, organization_main, assistant, radio or other.

number

string

The phone number. This is a free-form string.

Web Page

Attribute
Type
Description

type

string

Type of the web page. Could be profile, blog, homepage or work.

url

string

The web page url. This is a free-form string.

Suggest Edits

/contacts

 
gethttps://api.nylas.com/contacts
curl --request GET \
  --url https://api.nylas.com/contacts \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/contacts',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/contacts");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/contacts"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
[
    {
        "account_id": "x2x2x2x2x2x2x2x2x2x2x2",
        "birthday": "1960-12-31",
        "company_name": "Nylas",
        "emails": [
            {
                "email": "john@doe.com",
                "type": "work"
            }
        ],
        "given_name": "John",
        "id": "z3z3z3z3z3z3z3z3z3z3z3",
        "im_addresses": [
            {
                "im_address": "myaimaddress",
                "type": "aim"
            }
        ],
        "job_title": "Software Engineer",
        "manager_name": "Bill the manager",
        "middle_name": "Jacob",
        "nickname": "JD",
        "notes": "Loves ramen",
        "object": "contact",
        "office_location": "123 North Pole Dr",
        "phone_numbers": [
            {
                "number": "1 800 123 4567",
                "type": "mobile"
            }
        ],
        "physical_addresses": [],
        "picture_url": "https://api.nylas.com/contacts/427abc427abc427abc/picture",,
        "suffix": "Jr.",
        "surname": "Doe",
        "web_pages": []
    }
]

Query Params

limit
int32

Number of objects to return. Often defaults to 100. If set too high, requests may fail to prevent excessively large response bodies. See Pagination for more info.

offset
int32

Zero-based offset from default object sorting. See Pagination for more info.

email
string

Only return contacts containing this exact value for the contact’s email address. For example: /contacts?email=fred%40nylas.com

phone_number
string

Only return contacts containing this exact value as the contact's phone number. For example: /contacts?phone_number=4158889999

street_address
string

Only return contacts with this exact street address. For example: /contacts?street_address=1600%20Pennsylvania%20Ave

postal_code
string

Only return contacts containing this exact postal_code as one of the postal codes in the contact's physical address. For example: /contacts?postal_code=20500

state
string

Only return contacts with this exact value for the state in one of the contact's physical addresses. For example: /contacts?state=CA

country
string

Only return contacts with this exact value for the country in one of the contact's physical addresses. For example: /contacts?country=USA

source
string

Only return contacts from the address book or autogenerated contacts from emails. For contacts only from the address book: /contacts?source=address_book or for only autogenerated contacts: /contacts?source=inbox

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

You can get a list of contacts by sending a GET request to the /contacts endpoint. This will return a list of Contact JSON objects.

This list of contacts includes both contacts from the address book of the email provider and contacts that we auto generate from an accounts emails. To separate these out we have a source filter. Setting source=address_book will return only contacts from the email provider. Setting source=inbox will return only the autogenerated contacts that Nylas creates from an accounts emails.

Parameter Percent Encoding

It is important to note that parameter values must use percent-encoding (also known as URL encoding).

Exact Matches

We currently only support filtering on exact value matches in the database. That means the strings you filter on must be the exact strings stored on the contact in the database.

Suggest Edits

/contacts/{id}

 
gethttps://api.nylas.com/contacts/id
curl --request GET \
  --url https://api.nylas.com/contacts/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/contacts/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/contacts/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/contacts/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/contacts/id"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The contact id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Get a single contact by passing the contact id as a url parameter.

Suggest Edits

/contacts

 
posthttps://api.nylas.com/contacts
curl --request POST \
  --url https://api.nylas.com/contacts \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.nylas.com/contacts',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/contacts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.nylas.com/contacts");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/contacts"

headers = {'authorization': 'Authorization'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

given_name
string

Given name of the contact

middle_name
string

Middle name of the contact

surname
string

Surname of the contact

birthday
string

Birthday of the contact with format YYYY-MM-DD

suffix
string

Suffix (e.g: “Jr., Sr., III”)

nickname
string

Nickname of the contact

company_name
string

Name of the company that the contact works for

job_title
string

Job title of the contact

manager_name
string

Name of the manager of the contact

office_location
string

Location of the office of the contact, this is a free-form field

notes
string

Notes about the contact

emails
array

Array of Email objects

im_addresses
array

Array of IM Address objects

physical_addresses
array

Array of Physical Address objects

phone_numbers
array

Array of Phone Number objects

web_pages
array

Array of Web Page objects

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

You can create a new contact by sending a POST request to the /contacts endpoint. The API will take a Contact JSON object and return a new Contact with a valid id.

Suggest Edits

/contacts/{id}

 
puthttps://api.nylas.com/contacts/id
curl --request PUT \
  --url https://api.nylas.com/contacts/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.nylas.com/contacts/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/contacts/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.nylas.com/contacts/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/contacts/id"

headers = {'authorization': 'Authorization'}

response = requests.request("PUT", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The contact id

Body Params

given_name
string

Given name of the contact

middle_name
string

Middle name of the contact

surname
string

Surname of the contact

birthday
string

Birthday of the contact with format YYYY-MM-DD

suffix
string

Suffix (e.g: “Jr., Sr., III”)

nickname
string

Nickname of the contact

company_name
string

Name of the company that the contact works for

job_title
string

Job title of the contact

manager_name
string

Name of the manager of the contact

office_location
string

Location of the office of the contact. This is a free-form field

notes
string

Notes about the contact

emails
array

Array of Email objects

im_addresses
array

Array of IM Address objects

physical_addresses
array

Array of Physical Address objects

phone_numbers
array

Array of Phone Number objects

web_pages
array

Array of Web Page objects

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

You can update an existing contact by sending a PUT request to the /contacts/{id} endpoint. The API will take a Contact JSON object and update the contact with the data you supplied. Fields that aren’t defined in the JSON you provided won’t be updated. Fields that are defined in the JSON will be overwritten with the new values.

Suggest Edits

/contacts/{id}

 
deletehttps://api.nylas.com/contacts/id
curl --request DELETE \
  --url https://api.nylas.com/contacts/id \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.nylas.com/contacts/id',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/contacts/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.nylas.com/contacts/id");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/contacts/id"

headers = {'authorization': 'Authorization'}

response = requests.request("DELETE", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

id
string
required

The contact id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

You can delete an existing contact by sending a DELETE request to the /contacts/<id> endpoint.

Suggest Edits

/contacts/{id}/picture

 
gethttps://api.nylas.com/contacts/id/picture
curl --request GET \
  --url https://api.nylas.com/contacts/id/picture \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/contacts/id/picture',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/contacts/id/picture")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/contacts/id/picture");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/contacts/id/picture"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 200 OK
Server: nginx
Date: Mon, 05 Feb 2018 21:26:04 GMT
Content-Type: image/jpeg
Content-Length: 2388
Connection: close
Access-Control-Allow-Headers: Authorization,Accept,Cache-Control,X-Requested-With,Content-Type
Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS
Access-Control-Allow-Credentials: true
Nylas-API-Version: 2.0
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Content-Security-Policy: default-src https: 'unsafe-eval' 'unsafe-inline'; object-src 'none'

{BINARY DATA BLOB}

Path Params

id
string
required

The contact id

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 

Some contacts have profile pictures.To get a contacts picture, send a GET request to the /contacts/<id>/picture endpoint. If a contact has a picture associated with it, when you make a normal GET request for the contact, the picture url field will be filled out with the url to send the picture GET request.

The result is the header information shown above with binary data. If you pipe the result into a data file specified by Content-Type field in the header data, jpg for this example, you can open that file and view the picture.

curl --include --request GET \
  --url 'https://api.nylas.com/contacts/{id}/picture' \
  --header "authorization: <Authorization>" > picture.jpg
Suggest Edits

Limitations for Exchange accounts

 

Because of the way the Exchange protocol works, we unfortunately have to restrict Exchange contacts to these arbitrary limits:

  • Exchange contact phone numbers must have a non-null type
  • Exchange contacts can only have one or two home or business phone numbers
  • Exchange contacts only support three different email addresses. These addresses will have a type set to null by default, but you can change them to be work or personal.
  • Exchange contacts only support three different IM addresses. These addresses will have a type set to null by default.
  • Exchange contacts only support a single web page. This webpage will have a type set to null by default
Suggest Edits

Unsupported Phone Types

 

Google Contacts

  • Google Voice
  • Custom phone types

Exchange Contacts

  • Other
  • Other fax
  • Callback
  • Telex
  • tty/tdd
Suggest Edits

Search Overview

 

The search sub-endpoint is used to run a full-text search that is proxied to the account's provider. Results are matched with objects that have been synced, and are then returned.

The search endpoint returns 40 results by default. This endpoint supports Pagination so your application can request more objects, or iterate through all results.

For details on the query syntax for the most commmon providers, please see Google, Exchange/Outlook, Yahoo, and Generic IMAP.

Suggest Edits

Search Messages

 
gethttps://api.nylas.com/messages/search
curl --request GET \
  --url 'https://api.nylas.com/messages/search?q=q' \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/messages/search',
  qs: { q: 'q' },
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/messages/search?q=q")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/messages/search?q=q");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/messages/search"

querystring = {"q":"q"}

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

q
string
required

The search query

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

Search Threads

 
gethttps://api.nylas.com/threads/search
curl --request GET \
  --url 'https://api.nylas.com/threads/search?q=q' \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/threads/search',
  qs: { q: 'q' },
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/threads/search?q=q")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/threads/search?q=q");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/threads/search"

querystring = {"q":"q"}

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

q
string
required

The search query

Headers

Authorization
string
required

access_token as HTTP Basic Auth username

 
Suggest Edits

Webhooks Overview

 

Webhooks allow your application to receive notifications when certain events occur. For example, when a new email is received, Nylas will make a POST request to your URI endpoint letting you know information about the new message. You can specify what events you'd like to be notified about in the developer dashboard.

Webhooks are the recommended way to get notified of changes to the accounts you sync, because they're easier to integrate with your app and scale seamlessly with your growth.

Need help getting started with webhooks?

Check out the Node Ruby, and Python example projects to see how to start accepting notifications from Nylas.

The Webhook object

The webhook object links a callback URL to the types of notifications that should be sent to it. You can programmatically access information about the state of your webhook using the following urls.

Attribute Type Description
id string Globally unique object identifier
application_id string Reference to parent application object
callback_url string The URL that notifications are posted to
state string The state of the webhook. See the table below for possible values
triggers array Array containing a set of triggers describing what sort of notifications this webhook should receive. See the triggers table in "Creating a Webhook" for possible values
version string String describing what version the webhook is on

A webhook can have the following states:

State Description
active We are sending data for this webhook and receiving 200 responses
inactive The webhook has been disabled from the developer console and we are not sending data for it
failing We are trying to send data, but the callback URL is returning non-200 responses or timing out
failed We have received the maximum number of non-200 responses and are no longer sending data for this webhook

If Nylas has repeatedly failed to receive a 200 response from your server, your webhook will be marked as failing and we will notify you via the email associated with your Nylas developer account. If our requests continuously fail, we will also notify when the webhook has been disabled.

Note about failed webhooks

If your webhook reaches the failed state, you can re-activate it from the developer console. However, we will not send any past data once the webhook is re-activated. You will need to manually resync any data that was lost during that time.

Suggest Edits

Creating a Webhook

 

Webhooks for an application are configured from the Nylas Developer Dashboard. To configure a new webhook, go to the "Webhooks" section of your application and select "Add Webhook". You will need to provide:

  1. The full URI for the webhook. Since this is the endpoint the Nylas servers send notifications to, the URI must be accessible from the public internet for the webhook to work. It must be an HTTPS endpoint as well. The endpoint is verified by sending a verification request.

  2. The triggers to receive notifications for. The list of available triggers are:

Trigger Description
account.connected An account has been connected to your app
account.running An account is syncing and running properly
account.stopped An account was stopped or cancelled
account.invalid An account has invalid credentials and needs to re-authenticate
account.sync_error An account has a sync error and is no longer syncing
message.created A new message was sent or received
message.opened A tracked message has been opened by a message participant
message.link_clicked A link in a tracked message has been clicked by a message participant
thread.replied A participant replied to a tracked thread
contact.created A contact has been added to an account
contact.updated A contact has been updated on an account
contact.deleted A contact has been deleted from an account
calendar.created A calendar has been added to an account
calendar.updated A calendar has been updated on an account
calendar.deleted A calendar has been deleted from an account
event.created An event has been added to an account
event.updated An event has been updated on an account
event.deleted An event has been deleted from an account

You can create more than one webhook for your application; however, the webhook endpoints cannot be the same. For example, you may create a webhook to receive notifications for the message.created trigger, and another to receive notifications for the account.connected and account.stopped triggers, but the webhooks must have different callback URIs.

Verification Request

Nylas will check to make sure your webhook is valid by making a GET request to your endpoint with a challenge query parameter when you add the endpoint to the developer dashboard (or anytime you set the webhook state to active). All you have to do is return the value of the challenge query parameter in the body of the response. Make sure you aren't returning anything other than the exact value of the challenge parameter. Your application has up to ten seconds to respond to the verification request. The verification request is not retried automatically.

Enabling and disabling a Webhook

Webhooks are set to "active" by default. To disable a webhook, go to the Webhooks section of your application and change the webhook's state to inactive.

Suggest Edits

Receiving Notifications

 

Once a webhook has been successfully created, Nylas will send an HTTPS POST request to the configured endpoint when an event of interest occurs. If multiple changes occur at the same time, they may be included in the same notification. Please note that we will send webhooks for all messages in a mailbox if the account you are connecting is new to the Nylas system.

A request that times out or results in a non-HTTP 200 response code is retried once every 10 minutes, up to 60 times. Failing that, the webhook is retired and its state set to "failed".

We strongly recommend processing your webhook data asynchronously from our POST request to avoid timeouts. We timeout each request at 300 seconds (5 minutes).

Note about webhooks response code

You must return an exact HTTP response code of 200, otherwise Nylas will consider the POST a failure and will retry the request (even if you return a 203, for example).

Each request made by Nylas includes an X-Nylas-Signature header. The header contains the HMAC-SHA256 signature of the request body, using your client secret as the signing key. This allows your app to verify that the notification really came from Nylas.

The body of the request is in UTF-8 JSON format and contains details about the event.

Notification format

The webhook endpoint will receive a list of changes for the triggers specified while creating the webhook. Note that for security reasons, the actual changes are not included. Instead, the response contains the trigger type and object id for each change; you can retrieve the changed object with the corresponding API endpoints.

The body of the POST request is encoded as a UTF-8 JSON object with the following attributes:

Attribute Type Description
deltas array Array of delta objects

Each delta object has the following attributes:

Attribute Type Description
date unix timestamp Timestamp when the change occurred
type string The trigger for this notification
object string The changed object type
object_data object Contains the changed object's object type, account_id, object id and an attributes sub-object

The attributes sub-object has extra information about the object. Currently, attributes is only included in object_data for message.created triggers.

Attribute Type Description
received_date unix timestamp Timestamp when the message was originally received
thread_id string The thread_id that this message belongs to

For more information about message tracking and the corresponding metadata object type, see Message Tracking.

Suggest Edits

/webhooks

 
gethttps://api.nylas.com/a/client_id/webhooks
curl --request GET \
  --url https://api.nylas.com/a/client_id/webhooks \
  --header 'authorization: Authorization'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.nylas.com/a/client_id/webhooks',
  headers: { authorization: 'Authorization' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.nylas.com/a/client_id/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Authorization'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.nylas.com/a/client_id/webhooks");
xhr.setRequestHeader("authorization", "Authorization");

xhr.send(data);
import requests

url = "https://api.nylas.com/a/client_id/webhooks"

headers = {'authorization': 'Authorization'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Path Params

client_id
string
required

The client_id of your Nylas developer application

Headers

Authorization
string
required

client_secret passed as HTTP Basic Auth username