Only show these results:

Threads in Nylas API v3 Beta

Most email providers organize email messages both as individual messages, and as threads. Threads represent collections of messages that are related to each other and result from people replying to an email conversation.

When you look at threads from a code perspective, you can detect a thread and group email messages using several criteria (the message subject, recipients, senders, and so on). Grouping several messages into a thread provides a coherent view of an email conversation. In long or fast-moving conversations, threads help the reader follow the discussion.

In the Nylas API v3 Beta, the Threads API has been updated to give you more control over how you detect collections of messages, and how you respond to them.

The updated Threads API is available only if you have upgraded to the Nylas API v3 Beta and later. It is not available for API v2.7.

Threads are non-linear

Threads are organized non-linearly, as collections of related email messages. Email service providers use criteria such as the message subject, its recipients, and so on to collect email messages into threads. They also keep track of the message_ids for each email message in the thread.

Because all of a thread's message_ids are logged, you can reply to a specific email message by referencing its ID. This creates a new branch of the thread — similar to a tree structure — and the email messages in the new branch continue to be associated with the thread.

ℹ️ The /threads endpoint does not return the contents of email messages. To fetch the contents of a message, you send a request to the /messages endpoint instead. For example, you can send a request to the /threads endpoint to get a list of messages in a thread, and a request to the /messages endpoint to get an array of email messages with their body content.

Before you begin

Before you use the updated Threads API, you need the following prerequisites:

⚠️ Currently, the v3 Threads API does not support IMAP Grants.

Build a fully-fledged inbox with the Threads API

You can use the /threads endpoint to emulate popular inbox UIs, like Gmail or Outlook, which group email messages into threads. This gives users a simple, centralized view of their latest email conversation. By combining this view with calls to the /messages endpoint, you can build a fully-fledged inbox in your application.

Example: Return a thread

The following request returns a single thread associated with a specific Grant. Note that you must know the thread's id to request it.

curl --request GET \
  --url https://api.us.nylas.com/v3/grants/ca8f1733-6063-40cc-a2e3-ec7274abef11/threads/7ml84jdmfnw20sq59f30hirhe \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <API_KEY_OR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json'   
{
  "grant_id": "ca8f1733-6063-40cc-a2e3-ec7274abef11",
  "id": "7ml84jdmfnw20sq59f30hirhe",  // The thread's ID.
  "object": "thread",
  "has_attachments": false,
  "has_drafts": false,
  "earliest_message_date": 1634149514,
  "latest_message_received_date": 1634832749,
  "latest_message_sent_date": 1635174399,
  "participants": [
    {
      "email": "[email protected]",
      "name": "Renee Smith"
    },
    {
      "email": "[email protected]",
      "name": "Rebecca Lee Crumpler"
    }
  ],
  "snippet": "jnlnnn --Sent with Nylas",
  "starred": false,
  "subject": "Dinner Wednesday?",
  "unread": false,
  "message_ids": [  // A list of IDs for all messages in the thread.
    "njeb79kFFzli09",
    "998abue3mGH4sk"
  ],
  "draft_ids": [  // A list of IDs for all drafts in the thread.
    "a809kmmoW90Dx"
  ],
  "folders": [  // A list of folders that messages in the thread are associated with.
    "8l6c4d11y1p4dm4fxj52whyr9",
    "d9zkcr2tljpu3m4qpj7l2hbr0"
  ],
  "latest_draft_or_message": {
    "body": "Hello, I just sent a message using Nylas!",
    "date": 1635355739,
    "attachments": {
      "content": "YXR0YWNoDQoNCi0tLS0tLS0tLS0gRm9yd2FyZGVkIG1lc3NhZ2UgL=",
      "content_type": "text/calendar",
      "id": "4kj2jrcoj9ve5j9yxqz5cuv98",  // The attachment's ID.
      "size": 1708,
      "content_type": "application/ics",
      "filename": "invite.ics",
      "id": "70jcsv367jaiavt4njeu4xswg",  // The attachment's ID.
      "size": 1708
    },
    "folders": {  // A list of folders the latest message in the thread is associated with.
      "8l6c4d11y1p4dm4fxj52whyr9",
      "d9zkcr2tljpu3m4qpj7l2hbr0"
    },
    "from": {
      "name": "Renee Smith",
      "email": "[email protected]"
    },
    "grant_id": "41009df5-bf11-4c97-aa18-b285b5f2e386",
    "id": "njeb79kFFzli09",  // The message ID for the latest message in the thread.
    "object": "message",
    "reply_to": {
      "name": "Renee Smith",
      "email": "[email protected]"
    },
    "snippet": "Hello, I just sent a message using Nylas!",
    "starred": true,
    "subject": "Hello From Nylas!",
    "thread_id": "1t8tv3890q4vgmwq6pmdwm8qgsaer",  // The thread's ID.
    "to": {
      "name": "Geoff Dale",
      "email": "[email protected]"
    },
    "unread": true
  }
}

Because threads are non-linear, you can use one of the message_ids listed in the response to reply to a specific email message in the thread. This creates a new branch of the thread, and depending on who responds to it, the structure of the thread can resemble the example below.

A hierarchy diagram showing a thread with several branches.

Changes to the Threads API in v3 Beta

The Threads API has been retooled for the Nylas API v3 Beta. 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_message_or_draft 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 latest_draft_or_message.date.
  • The view=expanded query param is no longer supported.

What's next?

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