Version:
Only show these results:

Nylas v3 diff view

This page provides a terse, high-level description of the changes between Nylas v2.7 and v3.0.0. It's not intended to be a thorough description of how to upgrade and migrate your Nylas application, but a high-level list suitable for helping with scoping tasks, and to be used as a checklist.

Terminology changes in v3

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.

Changes to API format and use in v3

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

You must now include the version code in the endpoint URI, and Nylas v3 ignores the Nylas-API-Version header.

Changes to provider auth apps in v3

⛔️ Do not use production provider auth apps to test your upgrades to Nylas v3. This might prevent your end users from re-authenticating using the methods available in v2.x, and may invalidate your Support SLAs. Make these changes only on non-production apps until you're ready for full migration.

In Nylas v3, each Nylas application can have only one connector (previously "integration") for each provider. This might limit your ability to connect to legacy auth systems.

If you're upgrading from Nylas v2.7 to v3, keep the following things in mind:

  • You can use the same Google auth app as long as you have Pub/Sub set up.
  • You can reuse your Azure auth app if you remove any EWS/EAS scopes, add Graph scopes, and include personal accounts in the supported account types.

    ⚠️ Adding Graph scopes to your Azure app might prevent existing EWS or EAS accounts from re-authenticating. Make this change only on non-production apps until you're ready for full migration.

  • You must update your redirect URIs for any provider auth apps you create so they use the v3-specific endpoints.

New Hosted authentication methods

Most v2 Nylas applications that use Hosted authentication should implement the new Hosted OAuth method when you migrate them. This method involves storing and sending the application's API key only once. This returns a code that you can exchange for an access token, as in Nylas v2.7. Access tokens now expire after one hour, so you can choose to receive a refresh token as well to help re-authenticate when the access token expires.

Additional PKCE options are available to use with single page applications (SPAs) and mobile apps.

To access your end users' data using pure OAuth, pass the access token as the Bearer token in your request's auth header.

Refactored Nylas SDKs

The Nylas SDKs have been updated, improved, and refactored for v3. For more information, see the SDK documentation:

Deprecated APIs

  • /delta: No longer needed with v3 architecture.
  • /job-statuses: No longer needed with v3 architecture.
  • /components: Deprecated.
  • /outbox: Most functionality replaced by scheduled send.
  • Generate ICS file: POST /events/to-ics

Removed Nylas scopes

Nylas v3 removes Nylas scopes to reduce complexity and give you more control. Instead, you specify provider scopes only.

You can either create a login button for each provider that you support, or use the /v3/providers/detect endpoint to determine which provider an end user is authenticating with, so you can request the correct set of provider scopes.

Nylas application management in v3

You can create and manage v3 applications, access their client_ids, and generate API keys from the v3 Nylas Dashboard. You cannot create applications using the API.

🔍 The v3 Nylas Dashboard no longer displays client secret values for applications. Where you would previously use the client_secret in requests, you should now use your application's API key.

As of May 2024, the v3 Dashboard now supports both v2 and v3 Nylas applications, but doesn't include a version switcher. In v3 and later, the major version is encoded in the endpoint route.

Callback and redirect URIs

The redirect_uri used in the Hosted authentication flow has been renamed to callback_uri in Nylas v3. This helps to distinguish it from the Nylas redirect_uri, which provider auth apps use to forward OAuth requests to Nylas. The callback_uri used by webhook subscriptions is now called webhook_url to be more explicit.

In short, you'll encounter the following URIs in v3:

  • The callback URI is used during the Hosted authentication flow, and is set in your Nylas application.
  • The redirect URI is used during the provider OAuth flow, and is set in your provider auth app.
  • The webhook URL is part of a webhook subscription. This determines where Nylas sends webhook notifications.

New application endpoints

Removed application endpoints

  • Return application details: GET /a/<NYLAS_CLIENT_ID>
  • Update application details: PUT /a/<NYLAS_CLIENT_ID>
  • Get webhook IP addresses: GET /a/<NYLAS_CLIENT_ID>/ip_addresses

Connectors (previously called "integrations")

You must create a connector to store information about authentication sources for all v3 Nylas applications (including those using Native or Custom authentication, and any using virtual calendars). Connectors are currently available for Google, Microsoft Graph, and IMAP providers.

A v3 Nylas application can have only one connector per external provider, including one each for Google and Microsoft Graph. You can configure the default scopes for each provider.

New connector endpoints

Migrated connector endpoints

"Connected accounts" changed to "grants"

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.

Re-authenticating grants and webhook notifications

In v3, Nylas does not produce webhook notifications for events that happened before an end user authenticated with your application. When an end user's grant expires, Nylas stops sending webhook notifications for changes because it can no longer access the account's data.

If the grant expires then becomes valid within 72 hours, Nylas produces webhook notifications for the period that the grant was out of service. This means that your application may experience a high volume of incoming webhooks while Nylas syncs the events. The best practices guide includes suggestions for how to prepare to process a large number of incoming webhooks.

If the grant expires and becomes valid after that 72 hour period, Nylas does not send backfill notifications for events that occurred while their grant was out of service. In this case, look for the grant.expired and grant.updated notifications and query the Nylas APIs for objects that changed between those timestamps.

Accounts endpoints migrated to grants

New grants endpoints

Removed account endpoints

  • Cancel an account: POST /a/<NYLAS_CLIENT_ID>/accounts/<NYLAS_ACCOUNT_ID>/downgrade
  • Reactivate an account: POST /a/<NYLAS_CLIENT_ID>/accounts/<NYLAS_ACCOUNT_ID>/upgrade
  • Revoke all tokens: POST /a/<NYLAS_CLIENT_ID>/accounts/<NYLAS_ACCOUNT_ID>/revoke-all
  • Return token info: POST /a/<NYLAS_CLIENT_ID>/accounts/<NYLAS_ACCOUNT_ID>/token-info
  • Revoke an access token: POST /oauth/revoke
  • Return account details: GET /account

Changes to authentication in v3

The following sections describe changes to authentication in Nylas v3.

New authentication endpoints

Migrated authentication endpoints

Removed authentication endpoints

Native authentication has been renamed to "Custom authentication" in Nylas v3. Because of this change, the following auth endpoints have been removed:

  • Native auth - Send Authorization: POST /connect/authorize. Use the /v3/connect/custom endpoint instead.
  • Native auth - Exchange Token: POST /connect/token

Changes to webhooks in v3

Nylas v3 introduces many improvements and changes to webhooks that are beyond the scope of this brief diff view. See Webhooks in v3 for more details.

"Callback URI" changed to "webhook URL"

The callback_uri used by webhook subscriptions is now called webhook_url to make it explicit what this address is used for. This also helps distinguish it from the callback_uri and redirect_uri used in Hosted authentication.

New webhooks endpoints

Migrated webhooks endpoints

Changes to webhook triggers in v3

The .truncated suffix is new in v3. Watch for it, because it indicates a data payload that exceeds a base limit of 1MB. You will want to re-query for additional data in that case only.

Unchanged webhook triggers

  • contact.updated
  • contact.deleted
  • calendar.created
  • calendar.updated
  • calendar.deleted
  • event.created
  • event.updated
  • event.deleted
  • message.created
  • message.updated
  • folder.created
  • folder.updated
  • folder.deleted

New webhook triggers

  • grant.updated (Includes re-authentication.)
  • grant.deleted
  • grant.expired
  • message.send_success (Scheduled email messages only.)
  • message.send_failed (Scheduled email messages only.)
  • message.bounce_detected (Available for Google, Microsoft Graph, iCloud, and Yahoo.)
  • message.opened
  • message.link_clicked
  • thread.replied

Migrated webhook triggers

  • account.connected → grant.created

Removed webhook triggers

  • account.running: No longer needed due to architecture changes.
  • account.stopped: No longer needed due to architecture changes.
  • account.invalid: Use grant.deleted or grant.expired instead.
  • account.sync_error: No longer needed due to architecture changes.
  • contact.created: Use contact.updated instead.
  • job.successful: No longer needed due to architecture changes.
  • job.failed: No longer needed due to architecture changes.

Changes to Calendars and Events in v3

Nylas v3 includes the same basic ability to create, read, update, and delete both Events and Calendars (which contain Events). It also includes the following changes:

  • The Calendar and Events endpoints are available for Google, Microsoft Graph, iCloud, Exchange on-prem, and virtual calendars.

  • You now need a calendar_id for almost all calls to Events endpoints. You can specify it in one of the following ways:

    • Using the primary parameter to specify the primary calendar for the grant.
    • Look up and use the ID of the calendar that you want to work with.

  • You can now specify open hours by adding the default_open_hours parameter to the availability_rules object.

    • You can override the default settings by specifying a different availability for each participant.

  • Round-robin availability now uses the Nylas key5 metadata to indicate events that Nylas should consider when calculating the next available time amongst a group of participants.

  • The format for event start and end times has been simplified.

  • The format for recurring events has been simplified.

    • Recurring events no longer accept a recurrence time zone, and instead use the time zone specified in the when object to calculate the time for each event instance.

  • You can now list all calendars and events for a specific grant.

  • Added POST /v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>/send-rsvp endpoint.

  • Added the is_owned_by_user property for all Calendar calls.

  • (Gmail and Microsoft Graph only) Added the hex_color property for all Calendar calls.

  • (Microsoft Graph only) Added access to shared calendars using the Return Calendars endpoint.

  • Added the order_by query parameter for all Events GET calls.

  • Added the html_link property for all Events GET calls.

  • Added the capacity property for all Events calls.

  • You can no longer use a free_busy object to override or add busy data to an Availability request.

  • The time_slots and tentative_busy parameters for Availability requests have been removed.

Unchanged Calendar endpoints

Migrated Calendar endpoints

Deprecated Calendar endpoints

  • Get availability for multiple consecutive meetings: POST /calendars/availability/consecutive
  • Generate ICS file: POST /events/to-ics

Migrated Events endpoints

Removed Events parameters

  • event_id query parameter for GET calls.
  • updated_at_before for GET calls.
  • updated_at_before for GET calls.
  • participants query parameter for GET calls.
  • customer_event_id query parameter and property for all calls.
  • notifications property for POST and PUT calls.
  • original_start_time property for GET calls.
  • organizer_email property for GET calls.
  • organizer_name property for GET calls.
  • owner property is for GET calls.
  • message_id for GET calls.
  • event.recurrence.timezone for GET calls.

Changes to virtual calendars in v3

  • Virtual calendars now use the v3 Calendar and Events APIs, and all Calendar-related endpoint changes apply to virtual calendars.
  • Each grant can now have up to 10 virtual calendars.
  • You must now provide an identifier when you create a grant for a virtual calendar. This can be any arbitrary string.
  • Added the option to specify a primary calendar.
    • By default, the first virtual calendar associated with a grant is considered the primary.

Changes to Email in v3

  • All Messages and Drafts endpoints now require a grant_id, an email address, or — if you're using access token authentication — the /me/ construction.
  • Labels and Folders have been consolidated into Folders.
    • folder → folders for all Messages and Threads calls.
    • labels → folders for all Messages and Threads calls.
  • Files are now called Attachments.
    • Previously, you used the files endpoints to add files to messages. Now, you use the Drafts and Message-Send endpoints to add attachments, and the Attachments APIs to get information about the attachments. For more information, see Working with email attachments.
  • You can now send drafts.
  • You can schedule a send time for a message, and edit or delete scheduled send times.
  • You can now soft-delete messages and threads.
  • The new message.send_success and message.send_failed notifications allow you to track the results of a scheduled send.
  • The new message.bounce_detected notification is available to check for message bounces from Google, Microsoft Graph, iCloud, and Yahoo.
  • The schedule_id, send_at, and use_draft parameters have been added to POST calls.
  • The /messages/search endpoint has been deprecated. Instead, you now include a URL-encoded provider query string in a GET /v3/grants/<NYLAS_GRANT_ID>/messages request.
  • The /threads/search endpoint has been deprecated. Instead, you now include a URL-encoded provider query string in a GET /v3/grants/<NYLAS_GRANT_ID>/threads request.
  • The not_in and filename query parameters have been deprecated for GET calls.
  • The view=count query parameter has been deprecated for GET calls.
  • The events and cids properties have been deprecated for GET calls.
  • Nylas stores email messages from IMAP providers in a 90-day rolling window. After 90 days Nylas deletes the stored copies, and you can't retrieve them using the Nylas API once they're deleted. If you require access to IMAP messages older than 90 days, your project must store them.

New Email endpoints

Migrated Email endpoints

Removed Email endpoints

  • All /outbox endpoints (one GET can be migrated; see above).
  • All /files endpoints. Use the Drafts or Messages/Send endpoints instead. See Working with email attachments.

Changes to message tracking in v3

  • The tracking sub-object has been renamed tracking_options.
  • The payload in the recent object is now label.
  • The id in the recent object has been changed to click_id for link clicked tracking, and opened_id for message open tracking.

Changes to email search in v3

In Nylas v2, you could only search email messages on IMAP providers by subject and body contents. In v3, you can search using all standard IMAP SEARCH operators.

Changes to Threads in v3

The Threads API has been retooled for Nylas v3.

New Threads endpoint

Migrated Threads endpoints

  • All /threads endpoints → /v3/grants/<NYLAS_GRANT_ID>/threads

New Threads response fields

The Threads API now returns the following fields in request responses, in addition to the fields returned in v2.7:

  • latest_draft_or_message
  • has_drafts

Updated Threads response fields

  • first_message_timestamp → earliest_message_date
  • last_message_received_timestamp → latest_message_received_date
  • last_message_sent_timestamp → latest_message_sent_date

Removed Threads response fields and query params

  • labels response field: Threads are now organized by folders (see Changes to Folders and Labels).
  • last_message_timestamp response field: Replaced by latest_draft_or_message.date.
  • view=expanded query param: No longer supported.
  • view=count query param: No longer supported.

Changes to Folders and Labels in v3

In v3, Labels have been combined with Folders. Folders are a straightforward replacement for v3; Labels are pretty much the same.

Migrated Folders and Labels endpoints

Changes to Contacts in v3

Contacts are no longer listed in simple comma-separated values, but are now returned as JSON objects.

Migrated Contacts endpoints

Removed Contacts endpoints

The GET /contacts/<CONTACT_ID>/picture endpoint has been deprecated. Instead, you can now include the ?profile_picture=true query parameter in a Get Contact request to get the contact's profile picture.