Features and changes in Nylas API v3
The Nylas API v3 is in public beta. It might contain bugs, and might change before it is generally available. See the v3 Beta documentation for more information.
The Nylas v3 APIs are currently in Beta. This means that while many features are complete and ready to use, others are still being developed. All beta APIs might change as feedback comes in and we work to improve the experience.
What's included?
Some endpoints are not scheduled to be released during the Beta period, but will be available when v3 reaches General Availability (GA). The Nylas Contacts APIs (and associated webhook triggers) are scheduled for release in GA.
At this time, the Beta program includes the following features:
- Authentication with Google, Microsoft Graph, and IMAP using hosted OAuth, and custom authentication.
- Major improvements to Nylas webhook notifications.
- Improved versions of the Nylas Calendar and Events APIs.
- Virtual Calendar support for the v3 Calendar and Events APIs.
- Improved versions of the Nylas Email APIs (including Folders, Message send, Drafts, and so on).
What’s new?
The Nylas v3 APIs are a significant departure from the existing Nylas sync-engine model and greatly improve performance and reliability.
API 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.
API 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 the Nylas API 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 v3 Beta).
- Many other quality-of-life changes that drastically improve the Nylas developer experience.
Terminology changes
In v3 we've taken the opportunity to clarify some of the language we use to refer to the 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 old name), the documentation and Nylas UIs are being updated to use the clearer language.
- The integration object you created in your Nylas application to store provider details is now called a connector.
- Native authentication is now called Custom authentication.
- The provider integration applications for example your GCP project or Azure application, are now called provider auth applications .
- Service accounts, also sometimes called app permissions, are now called Bulk authentication grants to better reflect their use.
- The
redirect_uriset in Nylas applications using hosted authentication is now called thecallback_urito help distinguish it from the Nylasredirect_uriset in provider auth application.
Fast, direct access to providers
API 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 API 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
/job-statuses is 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.
Note: The v2 Dashboard cannot create v3-compatible Nylas applications, and the v3 Dashboard cannot manage v2 Nylas applications.
Authentication changes
There are three supported authentication mechanisms in API 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, API v3 also formalizes bulk authentication Grants (formerly known as "Service Accounts"). A bulk authentication Grant is a special kind of account used by an application or cloud provider compute workload rather than a person. Applications can use bulk authentication accounts to make and authorize API calls instead of users. This is supported by both Google and Graph API.
Changing account_id to grant_id
In API v3, the concept of "grants" (as in "the user granted you this access") replaces the concept of "connected accounts". This name better reflects Nylas' new offering and lays the groundwork for future enhancements and features.
The Nylas v3 APIs return a grant_id instead of an account_id in their responses to reflect this change. The new path format for Email, Calendar, and Contacts 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/messagesfor OAuth refresh/access token when you have a per-Grant token./v3/grants/[grant-id]/messagesfor API Key usage which can be used with any Grant ID.
Calendar and Events changes
The API v3 Beta 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.
By default, Events are no longer returned in any particular order. You can include the order_by=start query parameter to order returned Events by start time. This will make your queries match the API v2.7 behavior.
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 as well. In v3, timezone information uses an array of RRULE and EXDATE strings. With this change, EXRULE, RDATE, and TZID are no longer supported. The timezone is now inherited from the when object's timezone. DTSTART and DTEND are also no longer supported; instead, use the start and end times set in the when object. For more information, see RFC-5545.
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.
Email changes
API v3 allows you to send email messages instantly with a new simplified endpoint, or schedule when to send an email to an individual or to many recipients. It also allows you to include attachments within or with the email body, up to a maximum attachment size. For Instant Send, the limit is 10MB; for Scheduled Send, it's 3MB. These limits are expected to increase as development continues to GA.
The new endpoint to send messages in API v3 is /v3/message/send; it replaces the old /send, /v2/send, and /v2/outbox endpoints.
To switch from using the v2.7 Instant Send to the v3 Scheduled Send, use the send_at field in the request body. To send immediately using Scheduled Send, omit the send_at parameter.
Webhooks changes
Webhooks now include data in each payload that eliminate extra round trips to fetch data in response to notifications. See Webhooks in API v3 for more details on these changes, a list of the webhooks available in the v3 Beta, and suggestions for migration.
Contacts changes
Updated Contacts APIs are coming soon.
The body response for Contacts is now in JSON format. For example, event.owner used to be formatted as John Doe <[email protected]>, but is now rendered in JSON ({"email": "[email protected]", "name": "John Doe"}).
API changes
Changes to API format and use
The Nylas API endpoints and production domains have changed in API v3. They now follow the [service].[region].nylas.com schema:
api.nylas.com→api.us.nylas.comcanada.api.nylas.com→api.us.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> and Authorization: Basic <base64_encode(token + ":")> only. Users can no longer authenticate using Authorization: <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 will no longer honor 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:
- Call
GET /messages?limit=10without a query parametercursor. Nylas returns the first page of 10 results andnext_cursorin the API response body. The value is a string generated by the provider (for example,CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA). - Call
GET /messages?limit=10&cursor=CiAKGjBpNDd2Nmp2Zml2cXRwYjBpOXA. Nylas returns the second page of size 10. The response body includes a newnext_cursorvalue.
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.
Metadata filter allowed on key/value pair only
You can filter Metadata only on pre-defined keys. Filtering can be done with query_params. You cannot combine the Metadata filter with provider filters, except with calendar_id.