Managing threads

A thread is a conversation between one of your account links and one profile. Threads are never created directly: one appears when the first message is sent or received.

List threads

curl "https://inboxapp.com/api/v2/threads?folder=inbox&limit=20&expand=profile" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

{
  "data": [
    {
      "id": "l44e15irdq4db30i77cgphhx",
      "platform": "twitter",
      "platformId": "1566123362161725440:1876543210987654321",
      "accountLinkId": "df6jbw4h36qm5d9iu2sgn7kx",
      "profileId": "n7kxqm5d9iu2sgdf6jbw4h36",
      "contactId": "nq2r8v5ycx1t7m4hj6kd3wzb",
      "assigneeId": "r3km7xj9wq5p2bvnhfdteoly",
      "isRequest": false,
      "acceptanceState": "notRequired",
      "archived": false,
      "unread": true,
      "restrictions": [],
      "syncing": false,
      "typingIndicators": "teamDefault",
      "lastMessage": {
        "id": "p8rvk2m5j0xn4wq7ybftcael",
        "direction": "inbound",
        "createdAt": "2026-09-14T10:32:00.000Z"
      },
      "activity": {
        "preview": "Sounds good, send it over.",
        "direction": "inbound",
        "at": "2026-09-14T10:32:00.000Z"
      },
      "createdAt": "2026-09-01T09:00:00.000Z",
      "profile": { "id": "n7kxqm5d9iu2sgdf6jbw4h36", "username": "sarahchen" }
    }
  ],
  "nextCursor": "eyJhdCI6IjIwMjYtMDktMTRUMTA6MzI6MDAuMDAwWiJ9"
}

Folders

`folder`	Threads
`inbox`	Not archived, and not a request. The default
`noReply`	In `inbox`, with the latest activity from the other side
`requests`	Incoming requests the account hasn’t accepted or answered
`archived`	Archived, including archived requests
`all`	Every folder

Filters

Every filter narrows the folder. Repeat a key to match any of several values.

Parameter	Matches threads
`accountLinkId`	Of these account links
`platform`	On these platforms
`contactId`	With these contacts
`tag`	Whose contact has one of these tags, by ID or name
`status`	Whose contact has one of these statuses, by ID or name
`assigneeId`	Assigned to these members, directly or through the contact
`unassigned`	`true` for threads with no assignee
`campaignId`	These campaigns sent a message in
`q`	Matching display names, usernames and the activity preview

curl "https://inboxapp.com/api/v2/threads?folder=noReply&tag=hot-lead&tag=demo-requested&assigneeId=r3km7xj9wq5p2bvnhfdteoly" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

Find a thread with someone

Filter by account link and contact:

curl "https://inboxapp.com/api/v2/threads?accountLinkId=df6jbw4h36qm5d9iu2sgn7kx&contactId=nq2r8v5ycx1t7m4hj6kd3wzb&folder=all" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

An empty data array means there is no conversation yet. You don’t need one to send: see Working with messages.

Update a thread

PATCH only the fields you want to change.

update.ts

async function archive(threadId: string) {
  const response = await fetch(
    `https://inboxapp.com/api/v2/threads/${threadId}`,
    {
      method: "PATCH",
      headers: {
        Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ archived: true }),
    },
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${error.code}: ${error.message} (${error.requestId})`);
  }

  return response.json();
}

Field	Effect
`archived`	Moves the thread in or out of the archive
`unread`	Marks it read or unread
`assigneeId`	Sets this thread’s assignee. `null` falls back to the contact’s
`typingIndicators`	`enabled`, `disabled` or `teamDefault`

archived and unread also change on the platform when the account link has thread:archive:mutate or thread:read:mutate. Otherwise they change in Inboxapp only.

Assignment

A thread’s assigneeId is its own assignee, or else its contact’s default. To assign every conversation with a person, set assigneeId on the contact instead.

Requests

isRequest is true while a conversation is an incoming request the account hasn’t replied to or accepted. Requests live in the requests folder. Replying moves the thread to inbox.

Send a typing indicator

curl -X POST "https://inboxapp.com/api/v2/threads/l44e15irdq4db30i77cgphhx/typing" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

{ "status": "sent", "reason": null }

At most one per thread every 2.5 seconds: extra calls return skipped with reason: "rateLimited". Needs thread:typing:send.

Delete a thread

curl -X DELETE "https://inboxapp.com/api/v2/threads/l44e15irdq4db30i77cgphhx" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

{ "scope": "remoteAndLocal" }

remoteAndLocal means the conversation was also deleted on the platform. local means only Inboxapp’s copy was, because the platform doesn’t allow it.

Deleting a thread can’t be undone.

Getting started

Fundamentals

Configuration

Webhooks

Event types

Reference

Resources

Platforms

Team

Account Links

Contacts

Threads

Messages

Tags

Statuses

Colors

Events

List threads

Folders

Filters

Find a thread with someone

Update a thread

Assignment

Requests

Send a typing indicator

Delete a thread

​List threads

​Folders

​Filters

​Find a thread with someone

​Update a thread

​Assignment

​Requests

​Send a typing indicator

​Delete a thread

List threads

Folders

Filters

Find a thread with someone

Update a thread

Assignment

Requests

Send a typing indicator

Delete a thread