Version:
Only show these results:

Changes to Email APIs in Nylas v3

This page lists and explains the changes to Messages, Drafts, and related APIs between Nylas v2.7 and v3.

Changes to Messages and Drafts

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

Changes to Folders and Labels endpoints

  • All Labels endpoints have been replaced by Folders endpoints.
  • Added system_folder for Google in all Folders calls.
  • Added total_count in POST and PUT calls.
  • Added unread_count in GET calls.
  • Added attributes in GET and PUT calls.

Changes to the Send endpoint

  • Added an attachments property to POST calls.
  • Added send_at to POST calls for scheduled Messages.
  • Added is_draft to POST calls for scheduled send.

Changes to Files (Attachments)

  • The Files endpoints have been replaced by Attachments endpoints.
  • POST File upload has been deprecated.
  • GET /files has been deprecated.
  • DELETE /files/<file_id> has been deprecated.

Changes to message tracking

Nylas API v3 includes several small changes to message tracking to improve the clarity of tracking parameters and responses:

  • The tracking sub-object that you include in Send Message and Create Draft requests is now called tracking_options.
  • The tracking_options sub-object's payload field is now called label to better reflect its purpose.
    • Webhook responses now also reference the label field.
  • The recents array's id field is now called click_id for link clicked tracking, and opened_id for message open tracking.

Changes to email search in v3

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

Microsoft Graph mutable IDs

In general, Nylas v3 returns globally unique, immutable identifiers for messages and threads. This means that if you store a Nylas message_id or thread_id in your database, you can use it to get that message or thread at any time in the future. In some cases with Microsoft Graph, however, Nylas cannot guarantee that message or thread identifiers are immutable. This occurs when listing or searching with the following query parameters:

  • search_query_native
  • to
  • cc
  • bcc
  • any_email

This issue is specific to Microsoft Graph and affects only the listed query parameters. Nylas has not encountered this issue with any other providers.

To learn more about immutable identifiers and how it could affect your application, see Microsoft's official immutable identifiers documentation.

Changes to the Threads API in v3

The Threads API has been retooled for Nylas API v3. The following sections explain the changes.

New endpoint

  • DELETE /threads/<id>

New response fields

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

  • The latest_draft_or_message field, representing the most recent message or draft in the thread.
  • The has_drafts field, showing whether the thread has Drafts associated with it.

Updated response fields

The following response fields have been renamed:

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

Removals

  • The labels response field has been removed. Threads are now organized by folders, regardless of your email provider.
  • The last_message_timestamp response field has been moved and renamed. You can now find this information in the latest_draft_or_message.date sub-object.
  • The view=expanded query param is no longer supported.
  • The view=count query param is no longer supported.

What's next?

For more information about Nylas API v3, including how to start using it, you can browse the following resources: