Skip to main content
GET
/
api
/
v2
/
threads
import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

const { data: threads, error } = await inbound.thread.list()

if (error) {
  console.error('Error:', error)
} else {
  console.log(`Found ${threads.threads.length} threads`)
  console.log(`Total: ${threads.pagination.total}`)
}

{
  "threads": [
    {
      "id": "thread_abc123",
      "rootMessageId": "<msg123@example.com>",
      "normalizedSubject": "Support Request - Login Issues",
      "participantEmails": ["customer@example.com", "support@yourdomain.com"],
      "messageCount": 3,
      "lastMessageAt": "2024-01-15T14:30:00Z",
      "createdAt": "2024-01-15T10:00:00Z",
      "hasUnread": true,
      "isArchived": false,
      "latestMessage": {
        "id": "inbnd_3m4n5o6p7q8r",
        "type": "inbound",
        "subject": "Re: Support Request - Login Issues",
        "fromText": "John Doe <customer@example.com>",
        "textPreview": "Thanks for the password reset. I'm still having issues...",
        "isRead": false,
        "hasAttachments": false,
        "date": "2024-01-15T14:30:00Z"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1,
    "hasMore": false
  },
  "filters": {
    "search": "support",
    "unreadOnly": true
  }
}

​
Overview

This endpoint retrieves a paginated list of all email conversation threads for the authenticated user. Threads group related emails together based on Message-ID headers and subject lines, providing a conversation-based view of your emails.

​
Authentication

​
Authorization
string
required
Bearer token for API authentication. Format: Bearer YOUR_API_KEY

​
Query Parameters

​
limit
integer
default:"25"
Maximum number of threads to return per page. Range: 1-100.
​
offset
integer
default:"0"
Number of threads to skip for pagination. Must be non-negative.
​
search
string
Search query to filter threads by subject or participant email addresses.
​
unread
boolean
Filter threads by unread status. Set to true to only return threads with unread messages.
​
archived
boolean
Filter threads by archived status. Set to true to only return archived threads.
​
domain
string
Filter threads by domain. Returns only threads where at least one participant email is from the specified domain (e.g., example.com).
​
address
string
Filter threads by specific email address. Returns only threads where the specified email address is a participant.

​
Response

​
threads
array
required
Array of thread objects with summary information and latest message preview.
​
pagination
object
required
Pagination information for the current request.
​
filters
object
required
Applied filter information.

​
Examples

​
Basic Request

import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

const { data: threads, error } = await inbound.thread.list()

if (error) {
  console.error('Error:', error)
} else {
  console.log(`Found ${threads.threads.length} threads`)
  console.log(`Total: ${threads.pagination.total}`)
}

​
Filter by Search and Unread

import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

const { data: threads, error } = await inbound.thread.list({
  search: 'support',
  unread: true,
  limit: 10
})

if (error) {
  console.error('Error:', error)
} else {
  console.log(`Found ${threads.threads.length} unread support threads`)
}

​
Filter by Domain

Use the domain parameter to easily retrieve all threads for a specific domain. This is useful for filtering conversations by customer domain or organization.
import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

// Get all threads with participants from example.com
const { data: threads, error } = await inbound.thread.list({
  domain: 'example.com',
  limit: 50
})

if (error) {
  console.error('Error:', error)
} else {
  console.log(`Found ${threads.threads.length} threads with example.com participants`)
}

​
Filter by Email Address

Use the address parameter to retrieve all threads involving a specific email address. This is perfect for customer support workflows or account-based filtering.
import { Inbound } from '@inboundemail/sdk'

const inbound = new Inbound('YOUR_API_KEY')

// Get all threads with a specific participant
const { data: threads, error } = await inbound.thread.list({
  address: 'customer@example.com',
  limit: 25
})

if (error) {
  console.error('Error:', error)
} else {
  console.log(`Found ${threads.threads.length} threads with customer@example.com`)
}

​
Response

{
  "threads": [
    {
      "id": "thread_abc123",
      "rootMessageId": "<msg123@example.com>",
      "normalizedSubject": "Support Request - Login Issues",
      "participantEmails": ["customer@example.com", "support@yourdomain.com"],
      "messageCount": 3,
      "lastMessageAt": "2024-01-15T14:30:00Z",
      "createdAt": "2024-01-15T10:00:00Z",
      "hasUnread": true,
      "isArchived": false,
      "latestMessage": {
        "id": "inbnd_3m4n5o6p7q8r",
        "type": "inbound",
        "subject": "Re: Support Request - Login Issues",
        "fromText": "John Doe <customer@example.com>",
        "textPreview": "Thanks for the password reset. I'm still having issues...",
        "isRead": false,
        "hasAttachments": false,
        "date": "2024-01-15T14:30:00Z"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1,
    "hasMore": false
  },
  "filters": {
    "search": "support",
    "unreadOnly": true
  }
}

​
Error Responses

{
  "error": "Limit must be between 1 and 100"
}