Only show these results:
public-beta-v3

Nylas v3 diff view

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.

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

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_uri set in Nylas applications using hosted authentication is now called the callback_uri to help distinguish it from the Nylas redirect_uri set in provider auth application.

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.com
  • canada.api.nylas.com → api.us.nylas.com

Versioning is now handled by including the version code in the endpoint URI, and the v3 API ignores the old Nylas-API-Version header.

The Nylas v3 Dashboard only supports v3, and does not include a version switcher. You can continue using the v2 Dashboard for your v2 Nylas applications.

Provider authentication applications

You can reuse your existing provider auth applications. However, until you’re confident that your project is fully working on v3, you should use a development/testing application.

  • In v3, each Nylas application can have only one connector for each provider. This might limit your ability to connect to legacy authentication systems.
  • You can use the same Google auth application as long as you have PubSub set up.
  • You can reuse your Azure auth application if you remove any EWS/EAS scopes, add Graph scopes, and include personal accounts in the supported account types.
    • Changing your Azure application will prevent existing end-users from re-authenticating using v2 methods, so make this change only on non-production applications until you're ready for full migration.
  • You must update your redirect URIs for any provider auth apps you create so that they use the v3-specific endpoints.

If you use a production provider auth app specifically during Beta, it invalidates your support SLA for that application.

Hosted authentication options

Most applications using hosted authentication should implement the new Hosted OAuth method. This method involves storing and sending the client_secret once, and additional PKCE options are available for use with Single Page Applications (SPAs) and mobile apps.

These methods return a code you can exchange for an access token, as previously. Access tokens now expire after an hour, so you can choose to also receive a refresh token to help re-authenticate when the access token expires.

To access user data with pure OAuth, pass the access token in as the Bearer token in the auth header.

Native authentication has not changed except for the name change to "Custom auth" and the API call mechanics mentioned previously.

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.

Coming soon

Updated Contacts APIs and Neural APIs are coming soon.

Calendar endpoints coming soon

  • v3 replacement for Single meeting availability: POST /calendars/availability
  • v3 replacement for Calendar free or busy: POST /calendars/free-busy
  • v3 replacement for Multiple consecutive meetings availability: POST /calendars/availability/consecutive

Email endpoints coming soon

  • Replacements for all /threads and /resources endpoints.

Events endpoints coming soon

  • Generate ICS file: POST /events/to-ics
  • Return room resources information: GET /resources

Webhook triggers coming soon

  • message.opened
  • message.link_clicked
  • thread.replied
  • contact.created
  • contact.updated
  • contact.deleted
  • folder.created
  • folder.updated
  • folder.deleted

Nylas scopes removed

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

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

Nylas application management

You log in to the v3 Dashboard to create your v3 Nylas applications. You cannot create Nylas applications using the API.

Migrated application endpoints

  • Return application IP addresses: GET /a/<client_id>/ip_addresses -> Get IP addresses for webhooks: GET /v3/webhooks/ip-addresses

In v3, this endpoint is now included in the /v3/webhooks/ endpoints. It provides a list of IP addresses associated with the specified webhook for allowlisting or other security purposes.

Removed application endpoints

  • Return application details: GET /a/<client_id>
  • Update application details: PUT /a/<client_id>

You can log in to the v3 Dashboard to access and update your Nylas applications, access the client_id and client_secret, and generate API keys.

New application endpoints

Later in the Nylas v3 Beta, the application redirect_uri will be renamed to callback_uri to help distinguish it from the Nylas redirect_uri used by provider auth apps to forward OAuth requests to Nylas.

  • Get a list of applications: GET /v3/applications
  • Add redirect URI to application: POST /v3/applications/redirect-uris
  • Get all application redirect URIs: GET /v3/applications/redirect-uris
  • Get a specific redirect URI: GET /v3/applications/redirect-uris/<id>
  • Delete a redirect URI: DELETE /v3/applications/redirect-uris/<id>
  • Update a redirect URI: PATCH GET /v3/applications/redirect-uris/<id>

Connectors (previously called Integrations)

In v3, all Nylas applications (including those using native or custom auth, and any using Virtual Calendars) must create a connector to store information about authentication sources. The supported providers are Google, Microsoft Graph, and IMAP.

The supported providers are Google, Microsoft Graph, and IMAP.

Another change in v3, each Nylas application can only have one connector for each external provider, including one each for Google and Microsoft Graph.

You can now use each connector to configure default scopes for each provider.

Migrated connector endpoints

  • Detect provider: POST /connect/detect-provider → POST /v3/providers/detect

New connector endpoints

  • List connectors: GET /v3/connectors
  • Create connector: POST /v3/connectors
  • Get connector: GET /v3/connectors/<provider>
  • Delete connector: DELETE /v3/connectors/<provider>
  • Update connector: PATCH /v3/connectors/<provider>

Accounts change to Grants

In v3, Nylas removes the concept of "connected accounts" and instead works with Grants. This is a rename for clarity; Grants represent a specific set of scopes on a specific provider that the user has granted you.

Re-authenticating grants and webhook notifications

In API v3, the authentication and re-authentication processes do not produce historical webhooks (webhook notifications for events that happened before the auth completed)

This means that when a grant expires or is otherwise invalidated in v3, re-authenticating does not produce webhook notifications for events that occurred while the grant was out of service.

To find and backfill events that occurred while a grant was invalid, find the timestamps on the grant.expired and grant.updated webhooks that correspond to the grant in question. You might want to log or otherwise save these notifications when you receive them so you can query and analyze them later.

As soon as the user re-authenticates, you can use the Nylas APIs to directly query the provider for changes that happened during that time. You do not need to wait for any synchronization status to complete.

Migrate accounts endpoints to Grants

  • Return all accounts → List all Grants (GET /a/<client_id> → GET /v3/grants)
  • Return a specific account → Get a specific Grant (GET /a/<client_id>/accounts/<id> → GET /v3/grants/<grantId>)
  • Delete an account → Revoke a specific Grant (DELETE /a/<client_id>/accounts/<id> → DELETE /v3/grants/<grantId>)

New Grants endpoints

  • Update Grant: PATCH /v3/grants/<grantsId>
  • Get the current Grant: GET /v3/grants/me

Removed account endpoints

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

Authentication

Removed authentication endpoints

  • Native auth - Send Authorization: POST /connect/authorize
  • Native auth - Exchange Token: POST /connect/token

Migrated authentication endpoints

  • Hosted auth - Authenticate user → Hosted OAuth Authorization request (GET /oauth/authorize → GET /v3/connect/auth)
  • Hosted auth - Send authorization code → Hosted OAuth Token exchange (POST /oauth/token → POST /v3/connect/token)
  • Native auth → Custom auth (POST /connect/token → POST /v3/connect/custom)

New authentication endpoints

  • Hosted auth - Revoke Grant: POST /v3/connect/revoke

Webhooks

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

Migrated webhooks endpoints

  • Return all webhooks: GET /a/<client_id>/webhooks → GET /v3/webhooks
  • Create a webhook: POST /a/<client_id>/webhooks → POST /v3/webhooks
  • Return a webhook: GET /a/<client_id>/webhooks/<id> → GET /v3/webhooks/<id>
  • Update a webhook: PUT /a/<client_id>/webhooks/<id> → PUT /v3/webhooks/<id>
  • Delete a webhook: DELETE /a/<client_id>/webhooks/<id> → DELETE /v3/webhooks/<id>
  • Get IP addresses for a webhook: /a/{client_id}/ip_addresses -> GET /v3/webhooks/ip-addresses (in v2, this endpoint was listed under the Application endpoints as Return Application IP Addresses)

New webhooks endpoints

  • Rotate a webhook secret: POST /v3/webhooks/rotate-secret/<id>
  • Get IP addresses for a webhook (listed as Return Application IP Addresses in v2): GET /v3/webhooks/ip-addresses
  • Get mock payload endpoint: POST /v3/webhooks/mock-payload
  • Send test Event endpoint: POST /v3/webhooks/send-test-event

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

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

Migrated webhook triggers

  • account.connected → grant.created

New webhook triggers

  • grant.deleted
  • grant.updated (includes re-authentication)
  • grant.expired
  • message.send_success (scheduled messages only)
  • message.send_failed (scheduled messages only)
  • message.bounce_detected

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.
  • job.successful: No longer needed due to architecture changes.
  • job.failed: No longer needed due to architecture changes.

Triggers coming soon

  • message.opened
  • message.link_clicked
  • thread.replied
  • contact.created
  • contact.updated
  • contact.deleted
  • folder.created
  • folder.updated
  • folder.deleted

Calendar and Events

Calendar and Events endpoints are available for Google, Microsoft Graph, and Virtual Calendars in the API v3 Beta.

Calendar and Events APIs will be available for CalDav/WebDav (iCloud) when v3 is Generally Available (GA).

Calendars

A major change to Calendars is that a Calendar ID is now required for almost all calls. You can use the primary parameter to specify the primary Calendar associated with the Grant on the provider, use the Grant’s email address to specify its default Calendar, or look up the ID of the Calendar you want to work with and use that.

Migrated Calendar endpoints

  • Return all Calendars: GET /calendars → GET /v3/grants/<grant_id>/calendars
  • Create a Calendar: POST /calendars → /<grant_id>/calendars
  • Return a Calendar: GET /calendars/<id> → GET /v3/grants/<grant_id>/calendars/<calendar_id>
  • Update a Calendar: PUT /calendars/<id> → PUT /v3/grants/<grant_id>/calendars/<calendar_id>
  • Delete a Calendar: DELETE /calendars/<id> → DELETE /v3/grants/<grant_id>/calendars/<calendar_id>

Calendar endpoints coming soon

  • Replacement for Single meeting availability: POST /calendars/availability
  • Replacement for Calendar free or busy: POST /calendars/free-busy
  • Replacement for Multiple consecutive meetings availability: POST /calendars/availability/consecutive

Events

The format for recurring Events has been simplified. Recurring Events no longer accept a recurrence timezone, and instead use the timezone specified in your when object to calculate the time for event instances. The when object is a time: in epoch time, and a timezone: in IANA format.

Migrated Events endpoints

  • Return all Events: GET /events → GET /v3/grants/<grant_id>/events
  • Create an Event: POST /events → POST /v3/grants/<grant_id>/events
  • Return an Event: GET /events/<id> → GET /v3/grants/<grant_id>/events/<event_id>
  • Update an event: PUT /events/<id> → PUT /v3/grants/<grant_id>/events/<event_id>
  • Delete an Event: DELETE /events/<id> → DELETE /v3/grants/<grant_id>/events/<event_id>
  • Send RSVP: POST /send-rsvp → POST /v3/grants/<grant_id>/events/<event_id>/send-rsvp

Events endpoints coming soon

  • Generate ICS file: POST /events/to-ics
  • Return room resources information: GET /resources

Email: Messages, Drafts, send, and Files

  • All Messages and Drafts now need a grant_id or equivalent access method (email address, me, and so on).
  • You can now send Drafts.
  • You can schedule send time for a Message (and edit and delete scheduled send times).
  • Labels and Folders have been consolidated into Folders.
  • Files are now Attachments.
  • You can now delete Messages.
  • New webhooks have been added: message.send_success and message.send_failed for tracking scheduled-send results, and message.bounce_detected to check for bounces.
  • Added schedule_id to POST calls.
  • Added send_at to POST calls.
  • Added use_draft to POST calls.
  • The folder property is now folders in all Messages calls.
  • Deprecated the labels property in all Messages calls and replaced it with folders.
  • Deprecated the not_in query parameter in GET calls.
  • Deprecated the filename query parameter in GET calls.
  • Deprecated the events property in GET calls.
  • Deprecated the cids property in GET calls.

New Email endpoints

  • Delete a specific Message: DELETE /v3/grants/<grant_id>/messages/<message_id>
  • Get a specific scheduled Message: GET /v3/grants/<grant_id>/messages/schedules/<scheduleId>
  • Delete a specific scheduled-send instance: DELETE /v3/grants/<grant_id>/messages/schedules/<scheduleId>
    Note that this does not delete the Message, just the send-schedule.

Migrated Email endpoints

  • Return all Messages for a Grant: GET /messages → GET /v3/grants/<grant_id>/messages
  • Return a specific Message: GET /messages/<id> → GET /v3/grants/<grant_id>/messages/<message_id>
  • Update a specific Message: PUT /messages/<id> → PUT /v3/grants/<grant_id>/messages/<message_id>
  • Send a Message: POST /send → POST /v3/grants/<grant_id>/messages/send
  • Return all of a user’s Drafts: GET /drafts → GET /v3/grants/<grant_id>/drafts
  • Create a new Draft: POST /drafts → POST /v3/grants/<grant_id>/drafts
  • Return a specific Draft: GET /drafts/<id> → GET /v3/grants/<grant_id>/drafts/<draft_id>
  • Update a specific Draft: PUT /drafts/<id> → PUT /v3/grants/<grant_id>/drafts/<draft_id>
  • Delete a specific Draft: DELETE /drafts/<id> → DELETE /v3/grants/<grant_id>/drafts/<draft_id>
  • Retrieve all scheduled Messages: GET /outbox → GET /v3/grants/<grant_id>/messages/schedules
  • Get a specific File: GET /files/<id> → GET /v3/grants/<grant_id>/files/<file_id>

Removed Email endpoints

  • All /outbox endpoints (one GET can be migrated; see above).
  • All /files endpoints (one GET can be migrated; see above).

Email endpoints coming soon

Replacements for all /threads and /resources endpoints.

Folders and Labels

Labels are now combined with Folders.

Folders are a straightforward replacement for v3; Labels are pretty much the same.

Migrated Folders and Labels endpoints

  • Return all Labels → Return all Folders (GET /labels → GET /v3/grants/<grant_id>/folders)
  • Create a Label → Create a Folder (POST /labels → POST /v3/grants/<grant_id>/folders)
  • Return a Label → Return a specific Folder (GET /labels/<id> → GET /v3/grants/<grant_id>/folders/<folder_id>)
  • Update a Label → Update a specific Folder (PUT /labels/<id> → PUT /v3/grants/<grant_id>/folders/<folder_id>)
  • Delete a Label → Delete a specific Folder (DELETE /labels/<id> → DELETE /v3/grants/<grant_id>/folders/<folder_id>)
  • Get all Folders: GET /folders → GET /v3/grants/<grant_id>/folders
  • Create a Folder: POST /folders → POST /v3/grants/<grant_id>/folders
  • Return a specific Folder: GET /folders/<id> → GET /v3/grants/<grant_id>/folders/<folder_id>
  • Update a specific Folder: PUT /folders/<id> → PUT /v3/grants/<grant_id>/folders/<folder_id>
  • Delete a specific Folder: DELETE /folders/<id> → DELETE /v3/grants/<grant_id>/folders/<folder_id>

Contacts endpoints coming soon

Contacts endpoints are coming when API v3 is in GA.

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

Migrated Contacts endpoints

  • GET /contacts → GET /v3/grants/<grant_id>/contacts
  • POST /contacts → POST /v3/grants/<grant_id>/contacts
  • GET /contacts/<id> → GET /v3/grants/<grant_id>/contacts/<contact_id>
  • PUT /contacts/<id> → PUT /v3/grants/<grant_id>/contacts/<contact_id>
  • DELETE /contacts/<id> → DELETE /v3/grants/<grant_id>/contacts/<contact_id>
  • GET /contacts/<id>/picture → GET /v3/grants/<grant_id>/contacts/<contact_id>/picture

New Contacts endpoints

  • PUT /v3/grants/<grant_id>/contacts/<contact_id>/picture
  • DELETE /v3/grants/<grant_id>/contacts/<contact_id>/picture