Version:
Only show these results:

Features and changes in Nylas v3

Learn about features and changes in Nylas v3.

What’s new?

The Nylas v3 APIs are a significant departure from the existing Nylas sync-engine model and greatly improve performance and reliability.

Nylas v3 eliminates the need to store data with Nylas, and instead forwards requests to the provider and receives and handles responses. This lets you seamlessly connect with any provider using a simplified API. It also allows Nylas to prioritize security and privacy compliance, and simplifies GDPR/sub-processor compliance because Nylas no longer stores any end-user data.

v3 also consolidates endpoints with overlapping functions, unifies how they behave across the entire platform, and creates rigid contracts and better documentation. These changes are available to all customers, regardless of plan tier or enterprise packaging.

Overall, the platform changes significantly improve performance for many endpoints, allowing faster and more reliable operations.

With Nylas v3, you get...

  • Instant access to email messages and events upon connection, eliminating syncing delays.
  • Support for the Microsoft Graph API for seamless integration with Microsoft products.
  • Service accounts for easy development of complex applications and workflows.
  • An end to email queuing before send, ensuring immediate sending upon API call completion.
  • Bounce detection for emails to track undelivered messages (available in API v3).
  • Many other quality-of-life changes that drastically improve the Nylas developer experience.

Terminology changes

For Nylas v3, we've taken the opportunity to clarify some of the language we use to refer to parts of the Nylas system. While some of these changes are not yet available at the API level (meaning the API endpoints still reflect the v2 name), the documentation and Nylas UIs are being updated to use the clearer language.

  • The integration object that you create in your Nylas application to store provider details is now called a connector.
  • Provider integration applications (for example, your Google Cloud Platform project or Azure app) are now called provider auth apps.
  • Native authentication is now called Custom authentication.
  • Service accounts (sometimes called "app permissions") are now called bulk authentication grants to better reflect their use.
  • The redirect_uri set in Nylas applications that use Hosted authentication is now called the callback_uri. This helps to distinguish it from the Nylas redirect_uri set in provider auth apps.
    • The callback_uri used by webhook subscriptions is now called webhook_url to be more explicit about its use.

Fast, direct access to providers

Nylas v3 provides a fast query system that allows your application to retrieve data directly from the service providers. This means the object IDs Nylas returns come directly from the provider, and there is no more data sync, no waiting for syncs to complete (no more tracking job-status), and no need to monitor for deltas. This also means that Nylas no longer generates an additional "Nylas ID" for objects, and instead simplifies queries by using the provider's object IDs.

Using provider IDs instead of Nylas IDs

Nylas v3 provides a fast query system that allows your application to retrieve data directly from service providers. This means that the object IDs Nylas returns come directly from the providers, and there is no more data sync, no more waiting for syncs to complete, and no need to monitor for deltas. This also means that Nylas no longer generates an additional "Nylas ID" for objects, and instead simplifies queries by using the providers' object IDs.

Deprecating job-statuses

Jobs, and the /job-statuses endpoint are no longer used in API v3, as Nylas no longer syncs data from the providers. Because there is no longer a sync job, job_status_id no longer appears in the response payload.

Deprecating delta

The /delta endpoint is no longer available. API v3 includes significant improvements to the webhooks experience, which eliminates the need for additional API calls.

To find and backfill events that occurred while a grant was invalid, you now find the timestamps on the grant.expired and grant.updated webhooks that correspond to the grant in question. You can then use the Nylas APIs to directly query the provider for changes that happened during that time.

New Nylas v3 Dashboard

You can now create a v3 Nylas application from the v3 Dashboard. As of May 2024, you can also manage legacy Nylas v2 applications from the v3 Dashboard.

⚠️ Keep in mind: Although you can create and manage legacy v2 applications from the v3 Dashboard, the v2 Dashboard cannot create or manage v3 applications.

Authentication changes

There are three supported authentication mechanisms in Nylas v3:

  • Hosted OAuth with API key: This method starts by using the OAuth 2.0 Authorization Code method (response_type=code) to get user authorization and create a grant, but then uses an API key to make requests on behalf of the user.
  • Hosted OAuth with access token: This method includes both an access token that expires after one hour, and a refresh token to simplify re-authentication. This method also includes PKCE support for extra security on mobile and single-page applications (SPAs) that don't have a backend.
  • Custom authentication: Imports existing credentials or an existing refresh token, and creates a grant using it.

In addition, Nylas v3 also formalizes bulk authentication grants (formerly known as "service accounts"). A bulk auth grant is a special kind of account used by an application or cloud provider compute workload rather than a person. Applications can use bulk auth grants to make and authorize API calls instead of users. This is supported by both Google and Graph API.

In addition, Nylas API v3 also offers separate provider-specific connectors for iCloud and Yahoo accounts, in addition to the standard IMAP connector.

Do I need to re-verify my provider auth applications for v3?

In general, you shouldn't need to re-verify your provider authentication applications unless you are adding new features. However, Microsoft requires changes to comply with their new scopes, and two additional items might require changes if your auth app does not already include their scopes.

  • If you are using Microsoft Hosted OAuth in v2 without Graph scopes, you might need to re-verify your app when you include these items. Nylas recommends you start this process with a new Azure app in parallel so you can switch over without disrupting your end users workflows.
  • If you use thread.replied notifications, these now use the email.read scopes in v3, instead of the email.metadata scopes from v2.
  • If you use the Contacts APIs and want to use domain-level or inbox contacts, you may need to add scopes. If you only use address book contacts, no changes are required.

Changing account_id to grant_id

In Nylas v3, the concept of "grants" (as in "the end user granted you this access") replaces the concept of "connected accounts". This name better reflects the new offering and lays the groundwork for future enhancements and features.

The v3 APIs return a grant_id instead of an account_id in their responses. The new path format for Email and Calendar data also includes the grant ID, which references the specific account permissions used to retrieve the data.

All Email, Calendar, and Contacts APIs include a /v3/grants/{grant-id}/ prefix. For convenience, refer to an end user's grant using either their grant_id, their email address, or (if you are using an access token for their grant) the me construction. For example, GET /messages becomes one of the following in v3:

  • /v3/grants/me/messages for OAuth refresh/access token when you have a per-grant token.
  • /v3/grants/{grant-id}/messages for API key usage which can be used with any grant ID.

Calendar and Events changes

Nylas v3 includes the same basic ability to create, read, update, and delete both Events and Calendars (which contain Events). It also includes the new ability to list all Events and Calendars for a specific account, and the new Event RSVP endpoint allows users to set participant statuses for a given Event.

The calendar_id is now a required query parameter for most /events endpoints. This means that you can no longer list all Events from all Calendars, and you must be able to identify which Calendar an Event is associated with in order to retrieve, update, or delete it (you can set the calendar_id to the user's email address, or set it to default to select the default or main Calendar for the user on the service provider).

The requirements for Event start and end times have also been changed. The starts_before, starts_after, ends_before, and ends_after parameters have been simplified to only two variables: start and end. start is equivalent to ends_after and end is equivalent to starts_before. When you use either in a query, an Event is returned if any part of it occurs between the start and end times.

The timezone format for recurring events has been updated. In v3, recurring events use an array of RRULE and EXDATE strings. The time zone is now inherited from the when object. Nylas recommends that you use the when object to set the start time and the end time, instead of the Recurrence array. For more information, see the Create an Event reference documentation and RFC-5545.

Nylas v3 doesn't include an "Emailed Events" calendar for IMAP accounts.

Finally, round-robin has been updated. It now uses the value of the Nylas key5 metadata to indicate Events to consider when calculating the next available time amongst group members. Set key5 to a specific string to mark events to consider when calculating a round robin order.

Email changes

The v3 Email API allows you to send email messages instantly with a new, simplified endpoint (/v3/message/send). This replaces the v2.x /send, /v2/send, and /v2/outbox endpoints. You can also schedule when to send an email message to an individual or to many recipients, and include attachments with or within the email body, up to a maximum size. For Instant Send, the maximum attachment size is 10MB, and for Scheduled Send, it's 3MB.

To switch from using the v2.x Instant Send to the v3 Scheduled Send, add the send_at parameter in the request body and provide the time (in Unix timestamp format) when you want Nylas to send the email message. To send an email message immediately, omit the send_at parameter.

In v3 iCloud, Yahoo, and IMAP providers can retrieve email data up to 90 days old. For most providers, email webhook notifications are in real-time, however Yahoo and AOL accounts can take 5 minutes to deliver email webhooks. Nylas does not send webhook notifications for changes to email messages (for example folder or label changes), if the message being changed is older than 90 days.

Threads changes

The Threads API has been retooled for the API v3. You now have more control over how you detect collections of messages, and how you respond to them. See Threads in API v3 for more details on these changes.

Webhooks changes

Webhooks now include data in each payload that eliminate extra round trips to fetch data in response to notifications. See Webhooks in v3 for more information, a list of the webhooks available in API v3, and suggestions for migration.

Contacts changes

The Nylas body response for Contacts requests is now in JSON format (for example, the event.owner parameter was formatted as John Doe <johndoe@example.com>, but is now rendered as {"email": "johndoe@example.com", "name": "John Doe"}).

API changes

Changes to API format and use

The Nylas API endpoints and production domains have changed in v3. They now follow the [service].[region].nylas.com schema:

  • api.nylas.com → api.us.nylas.com
  • canada.api.nylas.com → api.us.nylas.com
  • ireland.api.nylas.com → api.eu.nylas.com

Deprecating HTTP

Nylas no longer supports HTTP (port 80). All Nylas traffic now goes through HTTPS (port 443).

Supporting only Bearer and Basic tokens

In v3, Nylas supports the Authorization: Bearer <token> only. Users can no longer authenticate using Authorization: <token> or Authorization: Basic <base64_encode(token + ":")>.

Changing URI path: version and Grant prefix

In v3, the API version is explicitly passed in the endpoint’s URI or path. The Nylas Dashboard no longer sets a default version for each Nylas application, and the Nylas API no longer honors the Nylas-API-Version header.

Changing pagination

Nylas API v3 replaces the pagination parameter offset with the new cursor query parameter. To use the cursor parameter, follow these steps:

  1. Call GET /messages?limit=10 without a query parameter cursor. Nylas returns the first page of 10 results and next_cursor in the API response body. The value is a string generated by the provider (for example, CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA).
  2. Call GET /messages?limit=10&cursor=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA. Nylas returns the second page of size 10. The response body includes a new next_cursor value.

In API v2.7, the page size default is 100 with no maximum page size. In API v3, the page size default is 50 with a maximum page size of 200.

Changes to Metadata filters

In Nylas v2, you could add up to 50 pairs of arbitrary metadata key-pairs to Calendars, Events, and Messages, and use those keys as query parameters to filter data from Nylas. This sometimes led to high latency when returning results.

In Nylas v3, you can still add metadata key pairs, however Nylas only indexes five specific keys: key1, key2, key3, key4, and key5. To continue using metadata filtering, you must write the values you want to filter by to the keys that Nylas indexes.

Nylas uses the key5 value when calculating round robin order. If you're using round-robin scheduling, you might want to make a plan for how you distribute queryable metadata among the five keys. Additionally, you can't use metadata filters with provider value filters, except for calendar_id.

Nylas v3 currently supports metadata on Calendars and Events only. Metadata support for other objects is coming soon.