Version:
Only show these results:

Upgrade a v2 project to use v3 Email APIs

This page explains how to upgrade your Nylas v2.x project to use the v3 Email API.

✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!

Changes to the Email API in v3

The following changes have been made to the Email API in Nylas API 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.

For a complete list of changes, see the v3 diff view.

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, Events, Messages, and Drafts.

Before you begin

Before you upgrade your Email API components, make sure you have already...

  • Upgraded your authentication systems from v2.x to v3.
  • Upgraded your webhooks from v2.x to v3.

Upgrade to v3 Email API

💡 Nylas recommends you test these changes in a non-production environment first. This helps to identify and troubleshoot any issues without impacting your end users or production environment.

There are a few changes you need to make to upgrade to the v3 Email API:

After you make those changes, you can do the following tasks:

Update endpoint references for v3

To update your application's endpoint references, find all instances of the v2 /messages, /threads, /send, /drafts, /labels, /folders, /outbox, and /files endpoints and change them to the appropriate v3 endpoints:

  • GET /messages → GET /v3/grants/{grant_id}/messages
  • GET /messages/{id} → GET /v3/grants/{grant_id}/messages/{message_id}
  • PUT /messages/{id} → PUT /v3/grants/{grant_id}/messages/{message_id}
  • All /threads endpoints → /v3/grants/{grant_id}/threads
  • POST /send → POST /v3/grants/{grant_id}/messages/send
  • GET /drafts → GET /v3/grants/{grant_id}/drafts
  • POST /drafts → POST /v3/grants/{grant_id}/drafts
  • GET /drafts/{id} → GET /v3/grants/{grant_id}/drafts/{draft_id}
  • PUT /drafts/{id} → PUT /v3/grants/{grant_id}/drafts/{draft_id}
  • DELETE /drafts/{id} → DELETE /v3/grants/{grant_id}/drafts/{draft_id}
  • GET /labels → GET /v3/grants/{grant_id}/folders
  • POST /labels → POST /v3/grants/{grant_id}/folders
  • GET /labels/<id> → GET /v3/grants/{grant_id}/folders/{folder_id}
  • DELETE /labels/<id> → DELETE /v3/grants/{grant_id}/folders/{folder_id}
  • GET /folders → GET /v3/grants/{grant_id}/folders
  • POST /folders → POST /v3/grants/{grant_id}/folders
  • GET /folders/<id> → GET /v3/grants/{grant_id}/folders/{folder_id}
  • PUT /folders/<id> → PUT /v3/grants/{grant_id}/folders/{folder_id}
  • DELETE /folders/<id> → DELETE /v3/grants/{grant_id}/folders/{folder_id}
  • GET /outbox → GET /v3/grants/{grant_id}/messages/schedules
  • GET /files/{id} → GET /v3/grants/{grant_id}/attachments/{attachment_id}
  • GET /files/{id}/download → GET /v3/grants/{grant_id}/attachments/{attachment_id}/download

🔍 Some endpoints include new response parameters. Nylas recommends you make test API calls in your non-production environment to catch and parse them before moving to production.

The following endpoints are deprecated in v3, so be sure to remove any references to them:

Modify parsing methods for threads

Some response fields for threads have been updated or removed in API v3, and new ones have been added. You should update your parsing methods to handle these changes.

The following response fields have been added:

  • latest_draft_or_message
  • has_drafts

The following response fields have been updated:

  • first_message_timestamp → earliest_message_date
  • last_message_received_timestamp → latest_message_received_date
  • last_message_sent_timestamp → latest_message_sent_date
  • last_message_timestamp → latest_draft_or_message.date.

Nylas API v3 also removes support for the view=expanded query parameter. Be sure to remove references to it where they appear in your code.

Modify parsing methods for folders

The folder parameter in all Messages and Threads now contains a list of folder_ids instead of an array of Folder objects. Be sure to update any code that handles parsing this field to handle this change.

Modify search methods for v3

Because the /messages/search and /threads/search endpoints are deprecated in API v3, you must update any code that references those endpoints. Instead, you now run a full-text search on an end user's inbox by including the search parameters in a Get all Messages or Get all Threads request.

API v3 also allows you to search messages on IMAP providers using all standard SEARCH operators.

Update message tracking for v3

The following message tracking parameters have been updated in API v3:

For migration purposes, you can subscribe to the following .legacy triggers to receive tracking data initiated by the v2 Email API:

The deltas array in the .legacy notifications contains v2 schema tracking data.

To use the .legacy triggers, you must:

  • Migrate the user's v2 account to a v3 grant.
  • Set up the v3 webhook endpoints with the corresponding tracking webhook triggers.
  • Make sure that the v2 account remains active. The v2 webhook endpoints must also be active with the corresponding tracking webhook triggers.

You should use v3 message tracking after you finish migrating your application.

Update webhook references for v3

Nylas Email API v3 supports the following notification triggers:

  • message.created
  • message.updated
  • message.opened
  • message.link_clicked
  • message.send_success
  • message.send_failed
  • message.bounce_detected (Available for Google, Microsoft Graph, iCloud, and Yahoo.)
  • thread.replied

The message.send_success and message.send_failed webhook triggers are new in API v3. You can use them to be notified when an email message that you sent using Scheduled Send is either delivered successfully, or is sent but not delivered.

message.bounce_detected is also new in API v3, and notifies you when an email message bounces (see Bounce detection in v3 for more information). Only Google, Microsoft Graph, iCloud, and Yahoo support this trigger, so be sure to double-check the end user's provider when setting it up.

(Optional) Integrate new endpoints

The following endpoints are new in API v3:

  • 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} (This doesn't delete the message, just the send-schedule.)
  • Delete a specific thread: DELETE /threads/<id>

You can choose to integrate some or all of them into your Nylas application.

Tuning v3 queries

Service providers like Google and Microsoft implement strict rate limiting (more about that here). Because Nylas v3 queries the providers directly, it is important that you make sure your API requests limit the amount of data they request so you don't hit these provider rate limits.

To avoid this you can use filtering and query selection to limit both the number of objects Nylas queries, and the amount of data Nylas returns about those objects. For example, if you're searching for an email message with a specific subject, you would ignore other returned fields like the message body. To make an efficient query, you could use a subject=<Your Subject here> query parameter, and then use select=subject,id to make sure Nylas only returns the information you need.

See the Developer Guide best practices section to learn more about rate limiting.

What's next?

You're nearly there! 🎉 If you haven't already, be sure to upgrade to the v3 Calendar and Contacts APIs. If you're done with the APIs, you can move on to upgrade any Nylas SDKs that your project uses.