Version:
Only show these results:

Versioning and v2 version history

The Nylas API is versioned. That means that whenever Nylas makes backward-incompatible API changes, we release a new version. This guarantees your app won’t break when Nylas adds more features to an existing API. We follow semantic versioning.

Currently Supported API Versions

Nylas currently supports v2.x and v3.x.

For the latest information about new releases and SDK features, see the latest changelog entries.

Additive changes are non-breaking

Nylas considers additive changes to be non-breaking. Functionally, this means we can add additional fields to an API response object without releasing a new API version. Make sure you build so your project can handle this possibility.

  • In v2.x, new Nylas applications are pinned to the latest version at the time of creation.
  • In v3, you specify the version using the API URI string, for example /v3/connect.

When you first begin building with a new version of the Nylas API, you should first create a new Nylas staging application for the new version. This way, you can test your code with the new version before updating your production environment.

Versioning HTTP Header

If you need to use a new API for a one-off request, you can also tell the Nylas API which version you would like to use, by passing the Nylas-API-Version HTTP header. This will not switch your app to a new version; rather, the HTTP request will execute with the specified API version.

curl --request GET --url https://api.nylas.com/threads -H "Nylas-API-Version: 2.1"

SDK

When using an SDK, it is possible that the version of the API that the SDK supports and the version of the API that the application is using differ. In this case, you will see a warning:

 may not support Nylas API . Upgrade package to ensure that it works properly.

To resolve this, update the SDK version using npm update or yarn upgrade.

Errors

If you’re trying to use a feature that is not available on the version of the API you’re using, you will get an HTTP error 400 with an error message asking you to upgrade to a later API version.

For example, trying to create a contact while using v1.0 of the API will result in the following error:

{ "type": "api_error",
  "message": "Contact creation isn't supported in the version of the Nylas API your app uses. Please update the API version for your app in the Nylas developer dashboard. https://dashboard.nylas.com" }

Legacy Nylas v2.x version history

1.0

Base version of the Nylas API. Any app created before October 10, 2017 is on version 1.0.

2.0

Breaking Changes

Version 2.0 adds breaking changes to the API. Review the changes and upgrade guide below.

Better support for contacts, including extended fields and the ability to create, update, and delete contacts for Exchange and Google. Upgrading from 1.0 to 2.0 is breaking change. Review our Transition to 2.0 guide.

2.1

Adds support for ical_uid field on events. The update doesn’t require you to make any changes to your application. The API changes were additive.

2.2

  • Virtual Calendars
  • Calendar Availability
  • Consecutive Availability
  • Neural Endpoints
  • Outbox
  • Room Resources

The update doesn’t require you to make any changes to your application. The API changes were additive.

2.3

We added graph as an authentication provider. This change supports:

The update doesn’t require you to make any changes to your application. The API changes were additive.

See changelog entry.

If you on an older API version, you can review our other transition guides. You can also read more about versioning.

2.4

Breaking Changes

Version 2.4 adds breaking changes to the API. Review the changes and upgrade guide below.

Microsoft authentication errors were not being sent as JSON. This update changes the responses to JSON. See changelog entry.

{
 "message": "You've entered invalid credentials",
 "type": "auth_error",
 "error": "Wrong username or password for https://outlook.com/EWS/Exchange.asmx"
}   
["Nylas_Error: You've entered invalid credentials.  Provider_Error: Wrong username or password for https://outlook.com/EWS/Exchange.asmx"]

If you are upgrading to version 2.4, make sure to take into account the new response format for Microsoft error messages.

2.5

You can now set the type field for Gmail accounts to any string value. This includes:

  • email.type
  • im_addresses.type
  • phone_numbers.type
  • physical_addresses.type
  • web_pages.type

The update doesn’t require you to make any changes to your application. The API changes were additive.

See changelog entry.

2.6

Breaking Changes

Version 2.6 is a breaking change.

We now require all Azure apps to have the client ID and client secret added in your dashboard. Microsoft deprecated Basic Authentication support for all Exchange Online accounts as of October 1, 2022.

See changelog entry.

2.7

See the Nylas v2.7 API documentation.