Skip to Content
GET
/api/v1/mailboxes/{mailboxId}/search

Searches email messages across subject, sender/recipient addresses, and body text using BM25 relevance ranking. Optionally filter by label, flags, or group matches by thread.

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

Query Parameters

q*string

Search keywords or phrases

Lengthlength <= 512
label?string

Restrict search to a specific label or folder

excludeRoles?array<>

System label roles to exclude: 'inbox', 'sent', 'drafts', 'trash', 'archive', 'junk' (e.g. 'trash,junk'). Unknown roles return 400 validation_failed.

hasFlags?string

Comma-separated flag names; a message matches only if ALL are set (e.g. flagged)

notFlags?string

Comma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)

limit?integer

Maximum messages to return (default 25, max 100 — or 2000 with fields=ids)

Range1 <= value <= 2000
cursor?string

Pagination cursor for next page of results

fields?"ids"

ids: answer the matching message IDS only, in rank order, under ids — no metadata rows, page cap 2000. What a client that needs a UID set (IMAP SEARCH) asks for: one call for what used to be twenty pages of full rows. Not combinable with group or snippet.

Value in"ids"
group?"thread"

Collapse matches to one top-ranked message per conversation thread

Value in"thread"
snippet?string

Whether to include highlighted search text snippets in results

Value in"true""false"

Response Body

Ranked search results

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

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

nextCursor?string

Opaque cursor for the next page; absent on the last page

results*array<>
scanWindow?integer

The ranking window's size: the 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.

snippets?array<>

Highlighted search excerpts

total?integer

Exact number of matching messages, under the same label and flag filters as the results. Absent when truncated (the ranking window clipped, so the count would describe the window rather than the match set) or when the page is past the end; absent also on grouped (group=thread) responses, whose conversation count is not known. Absent means unknown, never zero.

truncated?boolean

True if query matched more messages than maximum ranking window

Example Request
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/search?q=string'
Example Response
{
  "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"
    }
  ],
  "truncated": false
}