List Threads

Overview

List all email threads in an inbox. Threads group related messages based on email headers (In-Reply-To, References, Message-ID).

You can also use the account-wide variant: GET /v1/threads (requires Account API Key) to list threads across all inboxes.

Authentication

Authorizationstringpathrequired

Inbox API Key for inbox-scoped endpoint, or Account API Key for account-wide endpoint

Path Parameters

idstringpathrequired

The inbox ID (e.g., inb_abc123) - only for inbox-scoped endpoint

Query Parameters

labelstringquery

Filter threads by label (e.g., important, archive)

unreadbooleanquery

Filter to unread threads only (true) or read threads only (false)

beforestringquery

ISO 8601 timestamp - return threads updated before this time

afterstringquery

ISO 8601 timestamp - return threads updated after this time

limitnumberquery

Maximum number of threads to return (1-100)

offsetnumberquery

Number of threads to skip for pagination

sortstringquery

Sort field: updated_at or created_at

orderstringquery

Sort order: desc or asc

Account-wide endpoint only

inbox_idstringquery

Filter threads to a specific inbox (account-wide endpoint only)

searchstringquery

Full-text search across thread subjects (account-wide endpoint only)

Request

curl -X GET https://api.daimon.email/v1/inboxes/inb_abc123/threads?limit=20&unread=true \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o"

import { DaimonClient } from 'daimon-email';

const client = new DaimonClient({
  apiKey: 'dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o'
});

// Inbox-scoped
const threads = await client.inboxes.threads.list('inb_abc123', {
  limit: 20,
  unread: true,
  label: 'important'
});

console.log(`Found ${threads.total} threads`);
threads.threads.forEach(thread => {
  console.log(`${thread.subject} - ${thread.unread_count} unread`);
});

// Account-wide
const allThreads = await client.threads.list({
  limit: 50,
  search: 'order confirmation'
});

from daimon_email import DaimonClient

client = DaimonClient(
    api_key='dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o'
)

# Inbox-scoped
threads = client.inboxes.threads.list('inb_abc123', {
    'limit': 20,
    'unread': True,
    'label': 'important'
})

print(f"Found {threads['total']} threads")
for thread in threads['threads']:
    print(f"{thread['subject']} - {thread['unread_count']} unread")

# Account-wide
all_threads = client.threads.list({
    'limit': 50,
    'search': 'order confirmation'
})

Response

{
  "result": {
    "threads": [
      {
        "id": "thr_xyz789",
        "inbox_id": "inb_abc123",
        "subject": "Order Confirmation #12345",
        "labels": ["important", "order"],
        "message_count": 3,
        "unread_count": 1,
        "latest_message": {
          "id": "msg_def456",
          "from_address": "support@example.com",
          "preview": "Your order has been shipped...",
          "received_at": "2024-03-11T16:45:00Z"
        },
        "created_at": "2024-03-11T14:23:45Z",
        "updated_at": "2024-03-11T16:45:00Z"
      },
      {
        "id": "thr_abc456",
        "inbox_id": "inb_abc123",
        "subject": "Welcome to our platform",
        "labels": ["onboarding"],
        "message_count": 1,
        "unread_count": 0,
        "latest_message": {
          "id": "msg_ghi789",
          "from_address": "hello@platform.com",
          "preview": "Thanks for signing up! Here's how to get started...",
          "received_at": "2024-03-10T09:12:30Z"
        },
        "created_at": "2024-03-10T09:12:30Z",
        "updated_at": "2024-03-10T09:12:30Z"
      }
    ],
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true
  },
  "next_steps": [
    "Use GET /v1/inboxes/{id}/threads/{threadId} to retrieve full thread details with all messages",
    "Use PATCH /v1/inboxes/{id}/threads/{threadId} to update thread labels",
    "Use offset=20 to fetch the next page of results"
  ]
}

Response Fields

result.threadsarray

Array of thread objects

Thread object

idstring

Unique thread identifier (e.g., thr_xyz789)

inbox_idstring

The inbox this thread belongs to

subjectstring

Thread subject line

labelsarray

Array of label strings applied to this thread

message_countnumber

Total number of messages in this thread

unread_countnumber

Number of unread messages in this thread

latest_messageobject

Summary of the most recent message in this thread

Latest message object

idstring

Message ID

from_addressstring

Sender email address

previewstring

First 100 characters of message body

received_atstring

ISO 8601 timestamp when message was received

created_atstring

ISO 8601 timestamp when thread was created

updated_atstring

ISO 8601 timestamp when thread was last updated

result.totalnumber

Total number of threads matching the filter criteria

result.limitnumber

Maximum number of threads returned in this request

result.offsetnumber

Number of threads skipped

result.has_moreboolean

Whether there are more threads available to fetch

next_stepsarray

Suggested actions the agent can take next