Skip to content

List threads

GET
/v1/threads
curl --request GET \
  --url 'https://api.inboxcnx.com/v1/threads?participant=alice%40example.com&hasAttachment=true&source=gmail&providerThreadId=18c9a2f1b3d4e5f6&after=2026-08-01T00%3A00%3A00Z&before=2026-09-01T00%3A00%3A00Z&label=inbox&notLabel=trash&order=asc&include=total' \
  --header 'Authorization: Bearer <token>'

Lists the conversations in your grants’ stored mail, most recently active first, to show an inbox by thread. Returns threads matching every given query parameter (all parameters are combined with AND). Omit every parameter to list all threads the caller can see.

Sorted by most recently active thread first (order=desc, the default) or last (order=asc). Results are paginated: pass the previous response’s nextCursor or prevCursor back as cursor to fetch the next or previous page; null means there is none. include=total adds the number of matches. See the pagination guide.

To combine filters with OR or NOT, or to nest conditions, use POST /v1/threads/query instead: it accepts the same fields inside a filter tree.

Requires the read:messages scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
participant

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

string

Example 

alice@example.com

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

hasAttachment
Any of:
boolean

Only threads that do (true) or do not (false) contain at least one message with an attachment.

source

Only threads from this mail provider.

string
Allowed values: gmail m365 imap

Example 

gmail

Only threads from this mail provider.

providerThreadId

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

string

Example 

18c9a2f1b3d4e5f6

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

after

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

string format: date-time

Example 

2026-08-01T00:00:00Z

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

before

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

string format: date-time

Example 

2026-09-01T00:00:00Z

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

grantId

Only threads ingested through this connection grant.

string format: uuid

Only threads ingested through this connection grant.

label

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

string

Example 

inbox

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

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

Example 

trash

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.

order

Sort direction by most recent message. Default: desc (most recently active thread first).

string
Allowed values: asc desc

Sort direction by most recent message. Default: desc (most recently active thread first).

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

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.

limit

Page size, between 1 and 200. Default 50.

integer
>= 1 <= 200

Page size, between 1 and 200. Default 50.

include

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

string
Allowed values: total

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

Responses

Section titled “Responses”

200

Section titled “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": [
    {
      "id": "2d8f6a1c-7b3e-4c9d-a5f0-1e2b3c4d5e6f",
      "providerThreadId": "18f2b1c0a9e8d7f6",
      "source": "gmail",
      "subject": "Invoice 2026-1042",
      "participants": [
        {
          "name": "Acme Accounts",
          "email": "accounts@example.com"
        },
        {
          "name": null,
          "email": "owner@example.com"
        }
      ],
      "messageCount": 3,
      "hasAttachment": true,
      "firstMessageAt": "2026-10-21T14:02:00.000Z",
      "lastMessageAt": "2026-10-23T07:58:12.000Z",
      "lastInboundAt": "2026-10-23T07:58:12.000Z",
      "lastOutboundAt": "2026-10-22T09:15:40.000Z",
      "labels": {
        "system": [
          "inbox",
          "sent"
        ],
        "custom": []
      },
      "keywords": {
        "any": {
          "$seen": true,
          "$flagged": true
        },
        "all": {
          "$seen": false
        }
      }
    }
  ],
  "nextCursor": "eyJ2IjoiMjAyNi0xMC0yM1QwNzo1ODoxMi4wMDBaIn0",
  "prevCursor": null
}

400

Section titled “400”

Invalid query or malformed cursor

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

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

403

Section titled “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

Section titled “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"
  }
}