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.
- Previously, you used the
- 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
andmessage.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
, anduse_draft
parameters have been added toPOST
calls. - The
/messages/search
endpoint has been deprecated. Instead, you now include a URL-encoded provider query string in aGET /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 aGET /v3/grants/<NYLAS_GRANT_ID>/threads
request. - The
not_in
andfilename
query parameters have been deprecated forGET
calls. - The
view=count
query parameter has been deprecated forGET
calls. - The
events
andcids
properties have been deprecated forGET
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:
- Update endpoint references.
- Modify parsing methods for threads.
- Modify parsing methods for folders.
- Modify search methods.
- Update message tracking.
- Update webhook references.
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:
- All
/outbox
endpoints. - All
/files
endpoints. Use the Drafts or Messages endpoints instead.For more information, see Working with email attachments.
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_id
s 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:
tracking
→tracking_options
recent.payload
→recent.label
recent.id
→recent.click_id
for link clicked tracking, andrecent.opened_id
for message open tracking.
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.
Nylas sends .legacy
notifications only if the user's v2 account and webhook endpoint are active. 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.