List messages

GET

/v1/messages

const url = 'https://api.inboxcnx.com/v1/messages?q=invoice&from=alice%40example.com&to=bob%40example.com&after=2026-08-01T00%3A00%3A00Z&before=2026-09-01T00%3A00%3A00Z&minSize=1024&maxSize=10485760&hasAttachment=true&keyword=%24flagged&notKeyword=%24seen&label=inbox&notLabel=trash&providerThreadId=18c9a2f1b3d4e5f6&sourceMeta=%7B%22priority%22%3A%22high%22%7D&application=%7B%22crmId%22%3A%2242%22%7D&sort=receivedAt&order=asc&include=total';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.inboxcnx.com/v1/messages?q=invoice&from=alice%40example.com&to=bob%40example.com&after=2026-08-01T00%3A00%3A00Z&before=2026-09-01T00%3A00%3A00Z&minSize=1024&maxSize=10485760&hasAttachment=true&keyword=%24flagged&notKeyword=%24seen&label=inbox&notLabel=trash&providerThreadId=18c9a2f1b3d4e5f6&sourceMeta=%7B%22priority%22%3A%22high%22%7D&application=%7B%22crmId%22%3A%2242%22%7D&sort=receivedAt&order=asc&include=total' \
  --header 'Authorization: Bearer <token>'

Lists the stored mail of your grants, newest first, filtered by sender, date, folder, search text and more. Returns messages matching every given query parameter (all parameters are combined with AND). Omit every parameter to list all messages the caller can see.

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/messages/query instead: it accepts the same fields inside a filter tree.

Requires the read:messages scope.

Authorizations

apiKey
grantToken

Parameters

Query Parameters

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

Example

invoice

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.

from

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

string

Example

alice@example.com

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

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

string

Example

bob@example.com

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

after

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

string format: date-time

Example

2026-08-01T00:00:00Z

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

before

Only messages received strictly before this instant.

string format: date-time

Example

2026-09-01T00:00:00Z

Only messages received strictly before this instant.

minSize

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

integer | null

Example

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

maxSize

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

integer | null

Example

10485760

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

hasAttachment

Any of:

boolean
string

boolean

Only messages that do (true) or do not (false) carry at least one attachment.

keyword

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

string

Example

$flagged

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

notKeyword

Only messages that do NOT carry this JMAP keyword.

string

Example

$seen

Only messages that do NOT carry this JMAP keyword.

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

Example

inbox

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

notLabel

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

string

Example

trash

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

providerThreadId

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

string

Example

18c9a2f1b3d4e5f6

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

threadId

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

string format: uuid

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

grantId

Only messages ingested through this connection grant.

string format: uuid

Only messages ingested through this connection grant.

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

Example

{
  "sourceMeta": {
    "priority": "high"
  }
}

enrichmentContains

Only messages whose enrichment object contains this shape, e.g. {"application": {"crmId": "42"}} for what your enrichment endpoint returned. Same containment semantics as payloadContains. In a query string, pass it JSON-encoded.

Any of:

object
string

object

key

additional properties

sort

Sort axis. relevance requires q and is reachable to at most 1000 results. Narrow the query instead of paging further. Default: receivedAt.

string

Allowed values: receivedAt sentAt relevance

Sort axis. relevance requires q and is reachable to at most 1000 results. Narrow the query instead of paging further. Default: receivedAt.

order

Sort direction. Default: desc (newest, or best match, first).

string

Allowed values: asc desc

Sort direction. Default: desc (newest, or best match, 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

200

A page of message summaries, without body and attachments

application/json

object

data

required

Array<object>

object

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

required

Array<object> | null

object

name

required

string | null

email

required

string

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": [
    {
      "id": "c4a7e2b9-1d3f-4e6a-8b0c-5f2d9e7a1b34",
      "grantId": "9b2f0c4e-6a1d-4f3b-8c55-0d7e2a91b3c4",
      "providerMessageId": "18f2c4a9b7d01e3f",
      "providerThreadId": "18f2b1c0a9e8d7f6",
      "source": "gmail",
      "receivedAt": "2026-10-23T07:58:12.000Z",
      "sentAt": "2026-10-23T07:58:09.000Z",
      "subject": "Invoice 2026-1042",
      "from": [
        {
          "name": "Acme Accounts",
          "email": "accounts@example.com"
        }
      ],
      "sender": null,
      "to": [
        {
          "name": null,
          "email": "owner@example.com"
        }
      ],
      "cc": null,
      "bcc": null,
      "replyTo": null,
      "messageId": [
        "<20261023075809.4711@example.com>"
      ],
      "inReplyTo": null,
      "references": null,
      "size": 48213,
      "keywords": {
        "$seen": false
      },
      "labels": {
        "system": [
          "inbox"
        ],
        "custom": []
      },
      "language": "en",
      "preview": "Please find attached the invoice for October.",
      "hasAttachment": true,
      "raw": {
        "downloadUrl": "https://api.inboxcnx.com/v1/raw/c4a7e2b9-1d3f-4e6a-8b0c-5f2d9e7a1b34"
      },
      "enrichment": null,
      "stateAt": "2026-10-23T07:58:12.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": "eyJ2IjoiMjAyNi0xMC0yM1QwNzo1ODoxMi4wMDBaIn0",
  "prevCursor": null
}

400

Invalid query, malformed cursor, or a page beyond the relevance depth limit

application/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

application/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

application/json

object

error

required

object

code

required

string

message

required

string

Example ^generated

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

List messages

Authorizations

Parameters

Query Parameters

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

200

Example

400

Example generated

403

Example generated

503

Example generated

Example ^generated

Example ^generated

Example ^generated