Full-text search a mailbox
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.
bearerAuthAuthorizationBearer <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: [].
mailboxId*stringMailbox ULID identifier
q*stringSearch keywords or phrases
length <= 512label?stringRestrict 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?stringComma-separated flag names; a message matches only if ALL are set (e.g. flagged)
notFlags?stringComma-separated flag names; a message matches only if NONE are set (e.g. seen, for unread-only)
limit?integerMaximum messages to return (default 25, max 100 — or 2000 with fields=ids)
1 <= value <= 2000cursor?stringPagination 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.
"ids"group?"thread"Collapse matches to one top-ranked message per conversation thread
"thread"snippet?stringWhether to include highlighted search text snippets in results
"true""false"Ranked search results
application/json- response
ids?array<string>With fields=ids: the matching message IDs in rank order (results is then empty)
nextCursor?stringOpaque cursor for the next page; absent on the last page
results*array<>scanWindow?integerThe 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?integerExact 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?booleanTrue if query matched more messages than maximum ranking window
curl -X GET 'https://api.open.email/api/v1/mailboxes/string/search?q=string'{
"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
}List the keywords in use, with counts GET
Every distinct keyword on this mailbox's LIVE messages, most-used first then alphabetical, with how many messages carry each. Expunged messages are excluded…
Structured filter and query messages POST
Executes a structured query over mailbox messages with complex filters (combinators, header conditions, date ranges, flag states) and custom sort orders.