Threads

Threads group related messages into conversations. When a new message arrives, Nuntly automatically determines whether it belongs to an existing thread or starts a new one.

Threading algorithm

Nuntly uses the following logic to match incoming messages to threads, evaluated in order:

In-Reply-To header. If the incoming message has an In-Reply-To header, Nuntly looks for a message in the same inbox with a matching Message-ID. If found, the new message joins that thread.
References header. If no match is found via In-Reply-To, Nuntly checks the References header for any matching Message-ID in the same inbox.
Subject matching. If no header match is found, Nuntly normalizes the subject line (stripping prefixes like Re: and Fwd:) and looks for a thread in the same inbox with a matching normalized subject that had activity within the last 7 days.
New thread. If none of the above produce a match, a new thread is created.

List threads

You can list threads for a specific inbox. Filter by read status or spam flag.

import { Nuntly } from '@nuntly/sdk';

const nuntly = new Nuntly({
  apiKey: process.env.NUNTLY_API_KEY,
});

// List all threads in an inbox
const threads = await nuntly.inboxes.threads.list('ibx_01kabn43yqyxn2bx4ve84mczd3');

// Filter unread threads
const unreadThreads = await nuntly.inboxes.threads.list('ibx_01kabn43yqyxn2bx4ve84mczd3', {
  labels: 'unread',
});

// Filter spam threads
const spamThreads = await nuntly.inboxes.threads.list('ibx_01kabn43yqyxn2bx4ve84mczd3', {
  labels: 'spam',
});

Available filters

Parameter	Description
`labels`	Comma-separated labels to filter by (AND logic). Threads with the `spam` or `trash` label are excluded by default unless explicitly requested (for example `labels=spam`).
`cursor`	Cursor for pagination.
`limit`	Maximum number of results to return (1-30, default 30).

Thread fields

Field	Description
`id`	The unique thread identifier.
`domainName`	The domain name.
`inboxId`	The inbox this thread belongs to.
`subject`	The original subject line.
`lastMessageAt`	The timestamp of the most recent message.
`messageCount`	The number of messages in the thread.
`labels`	Aggregated labels from all messages in the thread (for example `unread`, `spam`).
`agentId`	The AI agent identifier, or `null`.

Retrieve a thread

Get the full details of a single thread. By default, retrieving a thread does not change its read status.

const thread = await nuntly.threads.retrieve('thr_01kabn43yqyxn2bx4ve84mczd3');

console.log('Subject:', thread.subject);
console.log('Messages:', thread.messageCount);
console.log('Last activity:', thread.lastMessageAt);

Pass markRead: 'true' as a query parameter to automatically remove the unread label from all messages in the thread: nuntly.threads.retrieve(threadId, { markRead: 'true' }).

List thread messages

Retrieve the messages in a thread. Messages are returned in chronological order (oldest first).

const messages = await nuntly.threads.messages.list('thr_01kabn43yqyxn2bx4ve84mczd3');

for (const message of messages.data) {
  console.log(`${message.from}: ${message.subject}`);
}

Update a thread

Update thread labels or agent assignment. Label operations apply to all messages in the thread.

// Mark as unread
await nuntly.threads.update('thr_01kabn43yqyxn2bx4ve84mczd3', {
  addLabels: ['unread'],
});

// Mark as spam
await nuntly.threads.update('thr_01kabn43yqyxn2bx4ve84mczd3', {
  addLabels: ['spam'],
});

// Assign an AI agent
await nuntly.threads.update('thr_01kabn43yqyxn2bx4ve84mczd3', {
  agentId: 'my-support-agent',
});

Update request fields

Field	Description
`addLabels`	Labels to add to all messages in the thread.
`removeLabels`	Labels to remove from all messages in the thread.
`agentId`	The AI agent identifier. Set to `null` to remove the agent.

Getting started

Sending

Receiving

Broadcast

Configuration

Observability

Webhooks

Best practices

Libraries & tools

Frameworks

Threading algorithm

List threads

Available filters

Thread fields

Retrieve a thread

List thread messages

Update a thread

Update request fields

Next steps

Messages

Send, reply, and forward

​Threading algorithm

​List threads

​Available filters

​Thread fields

​Retrieve a thread

​List thread messages

​Update a thread

​Update request fields

​Next steps

Messages

Send, reply, and forward

Threading algorithm

List threads

Available filters

Thread fields

Retrieve a thread

List thread messages

Update a thread

Update request fields

Next steps