Only show these results:

Versioning

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

Additive changes are non-breaking

Nylas considers additive changes to be non-breaking. This means we may add additional fields to an API response object without releasing a new API version, so your application should handle this possibility.

A new application will be pinned to the latest version at the time of application creation.

When integrating with a new version of our API, we recommend first creating a new Nylas staging application with the new version. This way, you can test that your code works with the new version, before updating your production environment.

Currently Supported API Versions

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: Latest Version

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 will be deprecating Basic Authentication support for all Exchange Online accounts as of October 1, 2022. Read more in Microsoft basic auth changes.

See changelog entry.

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