How to list Exchange email threads

Copy as Markdown

Open in

Exchange on-premises servers support conversation grouping through a ConversationId property that EWS assigns to each message. Nylas maps this directly to the Threads API, giving you a conversation view for self-hosted Exchange accounts through the same endpoint you’d use for Gmail or Outlook online.

This guide covers listing threads from Exchange on-prem accounts and the EWS-specific details: when to use EWS vs. Microsoft Graph, how ConversationId maps to threads, message ID behavior, and search limitations.

EWS vs. Microsoft Graph: which one?

This is the first thing to figure out. The two provider types target different Exchange deployments:

Provider type	Connector	Use when
Microsoft Graph	microsoft	Exchange Online, Microsoft 365, Office 365, Outlook.com, personal Microsoft accounts
Exchange Web Services	ews	Self-hosted Exchange servers (on-premises)

If the user’s mailbox is hosted by Microsoft in the cloud, use the Microsoft thread guide instead. The ews connector is specifically for organizations that run their own Exchange servers.

Microsoft announced EWS retirement and recommends migrating to Microsoft Graph. However, many organizations still run on-premises Exchange servers where EWS is the only option. Nylas continues to support EWS for these environments.

Why use Nylas for threads instead of EWS directly?

EWS is a SOAP-based XML API. Building a conversation view requires constructing XML SOAP envelopes for FindConversation operations, parsing nested XML responses, handling EWS-specific ConversationId and ConversationIndex fields, and managing autodiscovery to find the right server endpoint. Error responses come back as SOAP faults with nested XML structures.

Nylas replaces all of that with a JSON REST API. The /threads endpoint returns pre-grouped conversations with metadata. No XML, no WSDL, no SOAP. Authentication and autodiscovery are handled automatically.

Before you begin

You’ll need:

• A Nylas application with a valid API key
• A grant for an Exchange on-premises account
• An EWS connector configured with the ews.messages scope
• The Exchange server accessible from outside the corporate network (not behind a VPN or firewall that blocks external access)

New to Nylas? Start with the quickstart guide to set up your app and connect a test account before continuing here.

Exchange authentication setup

Create an EWS connector with the scopes your app needs:

Scope	Access
ews.messages	Email API (messages, threads, drafts, folders)
ews.calendars	Calendar API
ews.contacts	Contacts API

During authentication, users sign in with their Exchange credentials, typically the same username and password they use for Windows login. The username format is usually [email protected] or DOMAIN\username.

Users with two-factor authentication must generate an app password instead of using their regular password. See Microsoft’s app password documentation for instructions.

The full setup walkthrough is in the Exchange on-premises provider guide.

Network requirements

The Exchange server must be accessible from Nylas’s infrastructure:

• EWS must be enabled on the server and exposed outside the corporate network
• If the server is behind a firewall, you’ll need to allow Nylas’s static IP addresses (available on contract plans)

Accounts in admin groups are not supported.

List threads

Make a List Threads request with the grant ID. By default, Nylas returns the most recent threads. These examples limit results to 5:

RequestResponseNode.js SDKPython SDKRuby SDKJava SDKKotlin SDK

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads?limit=5" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json'

{
  "request_id": "1",
  "data": [
    {
      "starred": false,
      "unread": true,
      "folders": [
        "CATEGORY_PERSONAL",
        "INBOX",
        "UNREAD"
      ],
      "grant_id": "<NYLAS_GRANT_ID>",
      "id": "<THREAD_ID>",
      "object": "thread",
      "latest_draft_or_message": {
        "starred": false,
        "unread": true,
        "folders": [
          "UNREAD",
          "CATEGORY_PERSONAL",
          "INBOX"
        ],
        "grant_id": "<NYLAS_GRANT_ID>",
        "date": 1707836711,
        "from": [{
          "name": "Nyla",
          "email": "[email protected]"
        }],
        "id": "<MESSAGE_ID>",
        "object": "message",
        "snippet": "Send Email with Nylas APIs",
        "subject": "Learn how to Send Email with Nylas APIs",
        "thread_id": "<THREAD_ID>",
        "to": [{
          "email": "[email protected]"
        }],
        "created_at": 1707836711,
        "body": "Learn how to send emails using the Nylas APIs!"
      },
      "has_attachments": false,
      "has_drafts": false,
      "earliest_message_date": 1707836711,
      "latest_message_received_date": 1707836711,
      "participants": [{
        "email": "[email protected]"
      }],
      "snippet": "Send Email with Nylas APIs",
      "subject": "Learn how to Send Email with Nylas APIs",
      "message_ids": [
          "<MESSAGE_ID>"
      ]
    }
  ],
  "next_cursor": "123"
}

import 'dotenv/config'
import Nylas from 'nylas'

const NylasConfig = {
  apiKey: process.env.NYLAS_API_KEY,
  apiUri: process.env.NYLAS_API_URI,
}

const nylas = new Nylas(NylasConfig)

async function fetchRecentThreads() {
  try {
    const identifier = process.env.NYLAS_GRANT_ID
    const threads = await nylas.threads.list({
      identifier:identifier,
      queryParams: {
        limit: 5,
      }
    })

    console.log('Recent Threads:', threads)
  } catch (error) {
    console.error('Error fetching threads:', error)
  }
}

fetchRecentThreads()

from dotenv import load_dotenv
load_dotenv()

import os
import sys
from nylas import Client

nylas = Client(
    os.environ.get('NYLAS_API_KEY'),
    os.environ.get('NYLAS_API_URI')
)

grant_id = os.environ.get("NYLAS_GRANT_ID")

threads = nylas.threads.list(
  grant_id,
  query_params={
    "limit": 5
  }
)

print(threads)

require 'nylas'

nylas = Nylas::Client.new(api_key: '<NYLAS_API_KEY>')
query_params = { limit: 5 }
threads, _ = nylas.threads.list(identifier: '<NYLAS_GRANT_ID>', query_params: query_params)

threads.each {|thread|
  puts "#{thread[:subject]} | Participants: #{thread[:participants].map { |p| p[:email] }.join(', ')}"
}

import com.nylas.NylasClient;
import com.nylas.models.*;
import com.nylas.models.Thread;
import java.util.List;

public class ListThreads {
  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {
    NylasClient nylas = new NylasClient.Builder("<NYLAS_API_KEY>").build();
    ListThreadsQueryParams queryParams = new ListThreadsQueryParams.Builder().limit(5).build();
    ListResponse<Thread> threads = nylas.threads().list("<NYLAS_GRANT_ID>", queryParams);

    for(Thread thread : threads.getData()) {
      System.out.println(thread.getSubject());
    }
  }
}

import com.nylas.NylasClient
import com.nylas.models.*

fun main(args: Array<String>) {
    val nylas = NylasClient(apiKey = "<NYLAS_API_KEY>")
    val queryParams = ListThreadsQueryParams(limit = 5)
    val threads = nylas.threads().list("<NYLAS_GRANT_ID>", queryParams).data

    for (thread in threads) {
        println(thread.subject)
    }
}

The response includes a latest_draft_or_message object with the most recent message’s content. The same code works for Google, Yahoo, and IMAP accounts.

Filter threads

You can narrow results with query parameters. Here’s what works with Exchange accounts:

Parameter	What it does	Example
subject	Match on subject line	?subject=Weekly standup
from	Filter by sender	[email protected]
to	Filter by recipient	[email protected]
unread	Unread only	?unread=true
in	Filter by folder or label ID	?in=INBOX
received_after	After a Unix timestamp	?received_after=1706000000
received_before	Before a Unix timestamp	?received_before=1706100000
has_attachment	Only results with attachments	?has_attachment=true

Here’s how to combine filters. This pulls threads with unread messages from a specific sender:

curlNode.js SDKPython SDK

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/[email protected]&unread=true&limit=10" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

const threads = await nylas.threads.list({
  identifier: grantId,
  queryParams: {
    from: "[email protected]",
    unread: true,
    limit: 10,
  },
});

threads = nylas.threads.list(
    grant_id,
    query_params={
        "from": "[email protected]",
        "unread": True,
        "limit": 10,
    }
)

Search with search_query_native

Exchange supports the search_query_native parameter using Microsoft’s Advanced Query Syntax (AQS). You can combine search_query_native with any query parameter except thread_id.

curlNode.js SDKPython SDK

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads?search_query_native=subject%3Ainvoice&limit=10" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

const threads = await nylas.threads.list({
  identifier: grantId,
  queryParams: {
    searchQueryNative: "subject:invoice",
    limit: 10,
  },
});

threads = nylas.threads.list(
    grant_id,
    query_params={
        "search_query_native": "subject:invoice",
        "limit": 10,
    }
)

AQS queries must be URL-encoded. For example, subject:invoice becomes subject%3Ainvoice in the URL. The SDKs handle this automatically, but you’ll need to encode manually in curl requests.

The Exchange server must have the AQS parser enabled and search indexing active for search_query_native to work. If queries aren’t returning expected results, the Exchange admin should verify these settings.

See the search best practices guide for more on search_query_native across providers.

Things to know about Exchange threads

Exchange on-prem has native conversation support through ConversationId, but it behaves differently from Microsoft Graph in several important ways.

Exchange has native ConversationId

Like Exchange Online (Microsoft Graph), on-premises Exchange assigns a ConversationId to each message. Nylas maps this to the thread’s id field. This means Exchange threading is based on the server’s own grouping logic, not heuristic header matching. The grouping is more reliable than IMAP-based providers like Yahoo or iCloud.

Message IDs change when messages move, but thread IDs don’t

This is the most important Exchange-specific behavior. When a message moves from one folder to another, its Nylas message ID changes (this is expected EWS behavior). However, the thread_id remains stable because it’s based on the ConversationId, which doesn’t change when messages move.

If your app stores message IDs from the message_ids array, treat them as folder-specific pointers. The thread ID itself is safe to use as a permanent reference.

Threads span multiple folders

Like Microsoft Graph, Exchange threads can include messages across multiple folders (Inbox, Sent Items, Deleted Items). The thread’s folders array reflects all folders containing messages from that conversation. Use the in parameter to filter threads by folder.

Date filtering is day-level precision

Exchange processes received_before and received_after filters at the day level, not second-level. Even though Nylas accepts Unix timestamps, Exchange rounds to the nearest day. Results are inclusive of the specified day.

Search indexing affects query accuracy

Exchange relies on a search index for queries. If a message has just arrived but the search index hasn’t refreshed yet, threads containing that message may not appear in filtered results. The refresh interval is controlled by the Exchange administrator. Unfiltered list requests always return the latest threads.

Rate limits are admin-configured

Unlike cloud services, Exchange on-prem rate limits are set by the server administrator. If the Exchange server throttles a request, Nylas returns a Retry-After header. Use webhooks to avoid hitting rate limits.

EWS fallback to IMAP

If EWS isn’t enabled, Nylas can still connect via IMAP for email-only access. When using IMAP fallback, threading uses header-based grouping instead of ConversationId, and the 90-day message cache applies.

Paginate through results

The Threads API returns paginated responses. When there are more results, the response includes a next_cursor value. Pass it back as page_token to get the next page:

curlNode.js SDKPython SDK

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/threads?limit=10&page_token=<NEXT_CURSOR>" \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

let pageCursor = undefined;

do {
  const result = await nylas.threads.list({
    identifier: grantId,
    queryParams: {
      limit: 10,
      pageToken: pageCursor,
    },
  });

  // Process result.data here

  pageCursor = result.nextCursor;
} while (pageCursor);

page_cursor = None

while True:
    query = {"limit": 10}
    if page_cursor:
        query["page_token"] = page_cursor

    result = nylas.threads.list(grant_id, query_params=query)

    # Process result.data here

    page_cursor = result.next_cursor
    if not page_cursor:
        break

Keep paginating until the response comes back without a next_cursor.

What’s next

• Threads API reference for full endpoint documentation and all available parameters
• Using the Threads API for thread concepts and additional operations
• Messages API reference to fetch individual message content from threads
• List Exchange messages for message-level operations on Exchange accounts
• Search best practices for advanced search with search_query_native and AQS for Exchange
• Webhooks for real-time notifications instead of polling
• Exchange on-premises provider guide for full Exchange setup including authentication and network requirements