Query threads

POST

/v1/threads/query

curl --request POST \
  --url https://api.inboxcnx.com/v1/threads/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "operator": "OR", "conditions": [ { "participant": "alice@example.com" }, { "hasAttachment": true } ] }, "sort": [ { "property": "lastMessageAt", "isAscending": false } ], "limit": 25 }'

Finds conversations with a filter tree that combines conditions with AND, OR and NOT, for searches a flat query string cannot express. Conditions nest to any depth. Every condition field a plain GET /v1/threads accepts is also valid inside a filter tree.

A condition object (for example { "participant": "alice@example.com" }) matches threads satisfying all of its fields. Wrap conditions in an operator node to combine them explicitly:

{
  "operator": "OR",
  "conditions": [
    {
      "participant": "alice@example.com"
    },
    {
      "hasAttachment": true
    }
  ]
}

This matches threads where Alice is a participant OR the thread has an attachment.

Omit filter entirely to match every thread the caller can see. The filter tree is limited to 6 levels of nesting and 40 conditions in total; a tree that exceeds either limit is rejected with filter_depth_exceeded or filter_condition_count_exceeded.

Results are paginated the same way as GET /v1/threads; include: ["total"] adds the number of matches.

Requires the read:messages scope.

Authorizations

• apiKey
• grantToken

Request Body

Media typeapplication/json

object

filter

Any of:

object

object

operator

required

How to combine conditions. AND matches only if every condition matches; OR matches if any condition matches; NOT matches only if none of the conditions match.

string

Allowed values: AND OR NOT

conditions

required

Array<object> recursive

object

object

participant

Only threads with this exact address among their participants (senders and recipients).

string

hasAttachment

Any of:

boolean

boolean

string

string

Allowed values: true false

source

Only threads from this mail provider.

string

Allowed values: gmail m365 imap

providerThreadId

Only the thread matching this source provider’s own thread id (Gmail/M365/IMAP thread id).

string

after

Only threads whose most recent message was received at or after this instant (inclusive).

string format: date-time

before

Only threads whose most recent message was received strictly before this instant.

string format: date-time

grantId

Only threads ingested through this connection grant.

string format: uuid

label

Only threads in which at least one message carries this label (a system role or a custom label).

string

notLabel

Only threads in which at least one message does NOT carry this label. notLabel=trash leaves out threads whose every message is in the trash.

string

sort

How to sort the results, as an array with exactly one entry: [{ property, isAscending }]. A longer array is rejected. Omit to sort by most recently active thread first.

Array<object>

<= 1 items

object

property

required

string

Allowed values: lastMessageAt

isAscending

required

boolean

cursor

Opaque pagination cursor: a previous response’s nextCursor or prevCursor, passed back verbatim. A cursor issued under one sort order is rejected if reused with another.

string

limit

Page size, between 1 and 200. Default 50.

integer

>= 1 <= 200

include

total adds the number of matching results, counted up to 10000.

Array<string>

Allowed values: total

Example

{
  "filter": {
    "operator": "OR",
    "conditions": [
      {
        "participant": "alice@example.com"
      },
      {
        "hasAttachment": true
      }
    ]
  },
  "sort": [
    {
      "property": "lastMessageAt",
      "isAscending": false
    }
  ],
  "limit": 25
}

Responses

200

A page of threads, newest conversation first

Media typeapplication/json

object

data

required

Array<object>

object

id

required

string format: uuid

providerThreadId

required

string | null

source

required

string

Allowed values: gmail m365 imap

subject

required

string | null

participants

required

Array<object>

object

name

required

string | null

email

required

string

messageCount

required

integer

hasAttachment

required

boolean

firstMessageAt

required

string

lastMessageAt

required

string

lastInboundAt

required

string | null

lastOutboundAt

required

string | null

labels

required

object

system

required

Array<string>

Allowed values: inbox archive drafts sent trash junk all flagged important

custom

required

Array<string>

keywords

required

object

any

required

object

key

additional properties

boolean

all

required

object

key

additional properties

boolean

nextCursor

required

Pass back as cursor for the next page. Null on the last page.

string | null

prevCursor

required

Pass back as cursor for the previous page. Null on the first page.

string | null

total

Present only when requested with include. exact is false once the count reaches 10000 (or the depth cap of a relevance search); count is then that cap.

object

count

required

integer

exact

required

boolean

Example

{
  "data": [
    {
      "source": "gmail",
      "labels": {
        "system": [
          "inbox"
        ]
      }
    }
  ]
}

400

Invalid filter tree, malformed cursor, or a tree past the depth/count limit

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

The credential lacks the read:messages scope

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

The query exceeded the read timeout

Media typeapplication/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}