# Changes to Email APIs in Nylas v3 Source: https://developer.nylas.com/docs/new/in-v3/email-changes/ 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](#me-syntax-for-api-calls). - **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](/docs/v3/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//messages` request](/docs/reference/api/messages/get-messages/). - The `/threads/search` endpoint has been deprecated. Instead, you now include a URL-encoded provider query string in a [`GET /v3/grants//threads` request](/docs/reference/api/threads/get-threads/). - 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. - By default, Nylas now stores messages on IMAP providers in a cache for 90 days after they're received or created. - You can access messages older than 90 days by setting the `query_imap` parameter to `true` when you make a request to the following endpoints: [Get Message](/docs/reference/api/messages/get-messages-id/), [Get all Messages](/docs/reference/api/messages/get-messages/), [Get Draft](/docs/reference/api/drafts/get-draft-id/), [Get all Drafts](/docs/reference/api/drafts/get-drafts/), and the [Attachments endpoints](/docs/reference/api/attachments/). This directly queries the IMAP server instead of Nylas' cache. ## 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/` 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](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.4). ## 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](https://learn.microsoft.com/en-us/graph/outlook-immutable-id). ## 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/` ### 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: - [Nylas API v3 overview](/docs/v2/upgrade-to-v3/) - [Features and changes in API v3](/docs/v2/upgrade-to-v3/features-and-changes/) - [API v3 Getting Started guide](/docs/v3/getting-started/)