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.

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.
  • 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 webhooks have been added for tracking the results of a scheduled send.
  • The new message.bounce_detected webhook is available to check for message bounces.
  • 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 events and cids properties have been deprecated for GET calls.

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

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}/files/{file_id}

🔍 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.

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_message_or_draft
  • 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

The last_message_timestamp response field has been removed and replaced by latest_message_or_draft.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 more information about message tracking in v3, see the Message tracking documentation.

Update webhook references for v3

Nylas API v3 supports the following webhooks:

  • message.created
  • message.updated
  • message.opened
  • message.link_clicked
  • message.send_success
  • message.send_failed
  • (Gmail and Microsoft Graph only) message.bounce_detected
  • 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 Gmail and Microsoft Graph 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.

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.