Skip to Content
POST
/api/v1/mailboxes/{mailboxId}/search/query

Executes a structured query over mailbox messages with complex filters (combinators, header conditions, date ranges, flag states) and custom sort orders.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Request Body

application/json
  1. body
calculateTotal?boolean

Also return the total number of matches (an extra count).

collapseThreads?boolean

Return one representative message per conversation.

excludeRoles?array<>

System label roles whose mail this query must not return — e.g. ["trash", "junk"] for an All-Mail view. A message carrying ANY label with one of these roles is excluded, whatever else it carries. Says in one argument what a filter would need a label lookup and one bound value per label to say; a role no label answers to is simply not excluded.

fields?"ids"

ids: answer the matching message IDS only, in query order, under ids — no metadata rows, page cap 2000. For a client that needs an id set (an IMAP SEARCH with header or BODY criteria) and would otherwise download bodies to decide. Not combinable with snippet.

Value in"ids"
filter?|

An RFC 8621 §4.4 FilterCondition, or a boolean tree of them ({operator: AND|OR|NOT, conditions: [...]}). Bounded, and refused (never truncated) past the bound: the tree at most 32 levels deep and 512 nodes, and at most 64 bound values in total (an inMailboxOtherThan element costs one each).

limit?integer

Page size; capped at 200, defaults to 25 — or up to 2000 with fields: "ids".

Range1 <= value <= 2000
position?integer

Zero-based offset into the result list. A negative value counts back from the end (RFC 8620 §5.5).

snippet?boolean

Also return highlighted excerpts (subject + body preview) for the matched text terms of this page's results. Each excerpt costs a body read, so at most the first 50 results carry one.

sort?array<>

Up to 4 comparators; an id tiebreak is always appended so the order is total.

Itemsitems <= 4

Response Body

Search results page with optional total count and snippets

application/json
  1. response
ids?array<string>

With fields: "ids": the matching message IDs in query order (results is then empty)

limit?integer

Effective page size limit applied by the server

Formatint64
position*integer

Zero-based index of the first result within total matches

Formatint64
results*array<>

List of matching messages for the current page

scanWindow?integer

The cap that clipped: the collapsed results were drawn from the newest this-many matching messages. Present only beside truncated, so a client can say "more than N matches" with the N the server applied.

Formatint64
snippets?array<>

List of search term highlighted snippets for results

total?integer

Total number of matching messages (when calculateTotal was true)

Formatint64
truncated?boolean

Present (true) only on a collapseThreads query whose scan hit the server's row cap: the collapsed result set covers the newest matches, not all of them, and positional paging ends when that set does even though total (when requested) counts the whole match set. Present on EVERY page of such a query, not only the last, so a client can say so from page one.

curl -X POST 'https://api.open.email/api/v1/mailboxes/string/search/query' \
  -H 'Content-Type: application/json' \
  -d '{
  "calculateTotal": true,
  "filter": {
    "conditions": [
      {
        "after": "2026-08-01T00:00:00Z"
      },
      {
        "conditions": [
          {
            "from": "ada@example.com"
          },
          {
            "hasKeyword": "$flagged"
          }
        ],
        "operator": "OR"
      }
    ],
    "operator": "AND"
  },
  "limit": 50
}'
Example Response
{
  "limit": 25,
  "position": 0,
  "results": [
    {
      "auth": null,
      "bcc": null,
      "blobGen": "g1",
      "blobHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "cc": [],
      "deliveryMeta": null,
      "deliveryState": null,
      "envelopeFrom": "ada@example.com",
      "envelopeTo": "grace@acme.example",
      "flags": [
        "seen"
      ],
      "from": [
        {
          "email": "ada@example.com",
          "name": "Ada Lovelace"
        }
      ],
      "hasAttachment": true,
      "id": "01J9MSGA8C2E5H1K4M00000000",
      "inReplyTo": null,
      "keywords": [],
      "labels": [
        {
          "deleted": false,
          "modseq": 91842,
          "name": "INBOX",
          "uid": 4213,
          "uidValidity": 1722470400
        }
      ],
      "messageIdHeader": "<7f2a1c9e4b8d@mail.example.com>",
      "receivedAt": 1788081300,
      "referencesIds": [],
      "sentAt": 1788081272,
      "size": 48213,
      "snippet": "Hi Grace, attached is the Q3 report draft we discussed on Friday…",
      "subject": "Q3 report draft",
      "threadId": "01J9THRD5E8G1J4M7P00000000",
      "to": [
        {
          "email": "grace@acme.example",
          "name": null
        }
      ]
    }
  ],
  "snippets": [
    {
      "id": "01J9MSGA8C2E5H1K4M00000000",
      "preview": "attached is the <mark>Q3 report</mark> draft we discussed…",
      "subject": "<mark>Q3 report</mark> draft"
    }
  ],
  "total": 1
}