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.

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.

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.

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.

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.

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. They will be presented with a page like the one below.

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 client-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.

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.

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.

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.

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.

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.

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.

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

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.

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:

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.

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

Overview

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

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.

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.

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.

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:

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.

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.

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:

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.

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.

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

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

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).

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.

The Message Object

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

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.

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

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

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).

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.

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).

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

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.

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.