Query messages

POST

/v1/messages/query

curl --request POST \
  --url https://api.inboxcnx.com/v1/messages/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "operator": "OR", "conditions": [ { "q": "invoice" }, { "from": "accounts@example.com" } ] }, "sort": [ { "property": "receivedAt", "isAscending": false } ], "limit": 25 }'

Finds stored mail 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/messages accepts is also valid inside a filter tree.

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

{
  "operator": "OR",
  "conditions": [
    {
      "q": "invoice"
    },
    {
      "from": "accounts@example.com"
    }
  ]
}

This matches messages where the search text matches “invoice” OR the sender is accounts@example.com.

Omit filter entirely to match every message 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/messages; 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

q

Full-text search across subject, body, and every address field (from/to/cc/bcc). Matches inflected word forms in the message’s own language, not only the exact word typed.

string

>= 1 characters

from

Exact sender address match (not a substring search). Matches only if this exact address appears in From.

string

to

Exact recipient address match (not a substring search). Matches only if this exact address appears in To.

string

after

Only messages received at or after this instant (inclusive).

string format: date-time

before

Only messages received strictly before this instant.

string format: date-time

minSize

Only messages whose total size in bytes is at least this value.

integer | null

maxSize

Only messages whose total size in bytes is at most this value.

integer | null

hasAttachment

Any of:

boolean

boolean

string

string

Allowed values: true false

keyword

Only messages carrying this JMAP keyword, e.g. $flagged or $seen.

string

notKeyword

Only messages that do NOT carry this JMAP keyword.

string

label

Only messages carrying this label: either a system role (e.g. inbox, sent) or a source-specific custom label (e.g. a Gmail label).

string

notLabel

Only messages that do NOT carry this label, e.g. trash to leave out trashed mail.

string

providerThreadId

Only messages belonging to this source provider’s own thread id (Gmail/M365/IMAP thread id).

string

threadId

Only messages belonging to this InboxCNX thread id, as returned by GET /v1/threads.

string format: uuid

grantId

Only messages ingested through this connection grant.

string format: uuid

payloadContains

Only messages whose source-specific payload object contains this shape. Every field given here must be present in payload, matching at any nesting depth; extra fields elsewhere in payload do not disqualify a match. This checks containment only: ranges (greater/less than, between) and substring matches against nested values are not supported.

object

key

additional properties

enrichmentContains

Any of:

object

object

key

additional properties

string

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 receivedAt descending (newest first). Relevance sorting is not available here; use sort=relevance on GET /v1/messages instead.

Array<object>

<= 1 items

object

property

required

string

Allowed values: receivedAt sentAt

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": [
      {
        "q": "invoice"
      },
      {
        "from": "accounts@example.com"
      }
    ]
  },
  "sort": [
    {
      "property": "receivedAt",
      "isAscending": false
    }
  ],
  "limit": 25
}

Responses

200

A page of message summaries, without body and attachments

Media typeapplication/json

object

data

required

Array<object>

object

id

required

string format: uuid

providerMessageId

required

string

providerThreadId

required

string | null

source

required

string

Allowed values: gmail m365 imap

receivedAt

required

string

sentAt

required

string | null

subject

required

string | null

from

required

Array<object> | null

object

name

required

string | null

email

required

string

sender

required

Array<object> | null

object

name

required

string | null

email

required

string

to

required

Array<object> | null

object

name

required

string | null

email

required

string

cc

required

Array<object> | null

object

name

required

string | null

email

required

string

bcc

required

Array<object> | null

object

name

required

string | null

email

required

string

replyTo

required

Array<object> | null

object

name

required

string | null

email

required

string

messageId

required

Array<string> | null

inReplyTo

required

Array<string> | null

references

required

Array<string> | null

size

required

integer

keywords

required

object

key

additional properties

boolean

labels

required

object

system

required

Array<string>

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

custom

required

Array<string>

language

required

string | null

preview

required

string | null

<= 256 characters

hasAttachment

required

boolean

raw

required

object

downloadUrl

required

string | null

enrichment

required

object

application

object

key

additional properties

stateAt

required

string | null

deletedAt

required

string | null

grantId

required

string

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"
  }
}