SPB Git

Repository Public

SEARCH.md 8.8 KB

# SP Mail Next — search query language

One syntax for the web, macOS and iOS clients. It is parsed on the server (server/src/next/query.ts, a pure module covered by server/src/next/query.test.ts) and translated to JMAP filters per mailbox, so the three clients cannot diverge. It is a superset of the 0.3.0 web syntax (web/src/mail/search.ts): every query that client accepted keeps its meaning.

# Routes

Route Purpose
GET /api/next/search?q=&mailboxes=all|id,id&limit=50&cursor=&threads=1&tz=America/Toronto Search. { data: MessageSummary[], next_cursor, parsed: { terms, filters, errors } }
POST /api/next/search/parse { q, tz? } Parsed form only (chips, validation while typing). Never fails on bad input: defects are in errors
GET /api/next/attachments?… Attachment gallery (see below)
POST /api/next/attachments/zip Streams a ZIP of selected attachments

All routes need a device session (web cookie or native bearer), never an API key.

MessageSummary = { mailbox_id, email_id, thread_id, from: [{ email, name }], to: [{ email, name }], subject, preview, received_at, keywords: string[], mailbox_ids: string[] (JMAP folder ids), has_attachment, size, folder_roles: string[] }.

  • mailboxes: all (default) or a comma-separated list of mailbox ids. A mailbox of another user → 404.
  • limit: 1–100 (default 50).
  • threads=1: one result per thread and mailbox (the newest matching message).
  • tz: IANA time zone used for calendar dates (before:2026-01-15, today). Unknown or absent = UTC.
  • Results are merged across mailboxes by received_at, newest first. next_cursor is opaque, bound to the query (text, mailboxes, threads, tz) — reusing it with another query answers 400 invalid_cursor — and stable: mail arriving between two pages does not shift, duplicate or drop results of the following pages.

# Terms

A query is a list of terms separated by spaces. Terms are combined with AND. OR (upper case, or OU) between two terms combines them with OR and binds tighter than the implicit AND: from:alice OR from:bob devis = (from:alice OR from:bob) AND devis. A leading - negates a term: -from:alice, -facture, -"exact phrase", -has:attachment. Values containing spaces are quoted: subject:"rapport final". Parentheses are not supported.

Operator Synonyms Meaning JMAP
free word Anywhere in the message (headers, body) text
"exact phrase" Phrase search text (quoted)
from: de: expediteur: sender: Sender name or address from
to: à: a: pour: destinataire: To recipient to
cc: Cc recipient cc
bcc: cci: Bcc recipient (sent mail) bcc
subject: sujet: objet: Subject subject
body: corps: texte: contenu: Body only body
has:attachment avec:pj has:pièce avec:fichier contient:… Has at least one attachment hasAttachment
is:unread / is:read est:non-lu est:lu is:unseen is:seen Read state notKeyword / hasKeyword $seen
is:starred is:flagged est:suivi est:important Starred $flagged
is:pinned est:épinglé Pinned $pinned
is:snoozed est:reporté Snoozed $snoozed
is:followup est:relance est:à-suivre Follow-up flag $followup
is:answered is:forwarded is:draft est:répondu est:transféré est:brouillon $answered $forwarded $draft
label:<name> étiquette: libellé: tag: Label, by name (case and accents ignored). The name is resolved to its lbl_… keyword through the user's labels; the raw keyword is accepted too hasKeyword lbl_…
in:<folder> dans: dossier: folder: Folder role — inbox sent drafts trash junk archive (French: réception envoyés brouillons corbeille indésirables/spam archives) — or snoozed, or a folder name; in:all (in:anywhere, dans:tout) searches everywhere inMailbox
before: avant: older_than: Received before (see dates) before
after: après: since: depuis: newer_than: Received after after
larger: bigger: plusgrand: Size ≥ value minSize
smaller: pluspetit: Size ≤ value maxSize
filename: fichier: file: nom: An attachment name contains the value (case and accents ignored) hasAttachment + server-side check of the attachment names

An unknown key (note:abc, https://…, 12:30) is not an operator: the whole token is searched as free text, as in the 0.3.0 client.

# Dates

  • YYYY-MM-DD (or YYYY/MM/DD), today (aujourd'hui), yesterday (hier): calendar days in the tz zone. after: starts at 00:00 of that day; before: includes the day (it ends at 00:00 of the next day), exactly as the 0.3.0 web client did.
  • Durations — 12h, 7d (7j), 2w, 3m, 1y (1a): the instant "now minus the duration", for both operators. after:7d = the last seven days; before:3m = older than three months.

# Sizes

A number with an optional unit, multiples of 1024: 500, 10k (10kb, 10ko), 5m (5mb, 5mo), 1g. Decimals are accepted (1.5m).

# Default scope

Without a positive in: term, every folder is searched except Trash and Junk. in:trash, in:junk or in:all lift that restriction. -in:sent excludes a folder and keeps the default scope.

# Parsed form and errors

json
{
  "terms": [{ "op": "from", "value": "alice", "negated": false, "raw": "from:alice", "start": 0, "end": 10, "group": 0 }],
  "filters": { "operator": "AND", "conditions": [{ "from": "alice" }, { "notIn": ["trash", "junk"] }] },
  "errors": []
}
  • terms: one entry per accepted token, with its position in the query. Terms sharing a group are OR-ed; groups are AND-ed. before:/after: carry date (the UTC instant actually compared), larger:/smaller: carry bytes, quoted free text carries phrase: true. value is normalised for is: (unread, starred…) and in: (inbox, trash, all…).
  • filters: the mailbox-independent logical tree, for display. Folder and label references stay symbolic ({ "in": "inbox" }, { "label": "Clients" }, { "filename": "x" }, default scope { "notIn": ["trash","junk"] }).
  • errors: { token, start, end, code, message }. A token in error is ignored; the rest of the query still runs. The parser never throws.
Code Cause
empty_value from: with nothing after the colon
invalid_value unknown is: state, or has: other than attachment
invalid_date not a date, today/yesterday or a duration
invalid_size not a size
dangling_or OR not standing between two terms
filename_in_or filename: used as a branch of an OR (it is then treated as has:attachment)
unknown_label no label has that name — the term matches nothing
unknown_folder no selected mailbox has that folder — the term matches nothing (a folder present in only some mailboxes simply restricts the search to those)
query_too_long / too_many_terms more than 1000 characters / 50 terms; the rest is ignored

# Attachments

GET /api/next/attachments?mailboxes=&kind=&min_size=&max_size=&q=&from=&after=&before=&limit=50&cursor=&tz= → { data: Attachment[], next_cursor }, newest message first, Trash and Junk excluded.

Attachment = { mailbox_id, email_id, thread_id, blob_id, part_id, name, type, size, kind, from, subject, received_at, download_url, inline_ok }.

  • kind (one or several, comma-separated): image, pdf, document, spreadsheet, archive, audio, video, other — from the MIME type, then the file extension when the type is generic.
  • q filters on the file name (case and accents ignored); from on the sender; after/before take the same date values as the query language or an ISO 8601 date; min_size/max_size are bytes.
  • Images embedded in a message body (cid:, inline) are not listed.
  • download_url is the existing gateway route /api/jmap/{mailbox}/download/{accountId}/{blobId}/{name}?accept={type}: always served as an attachment with a sandboxing CSP. inline_ok is true for the image types that route accepts to display with &inline=1 (PNG, JPEG, GIF, WebP).

POST /api/next/attachments/zip { items: [{ mailbox_id, email_id, blob_id, name? }], filename? } streams application/zip (deflate, UTF-8 names). Limits: 50 items, 200 MB by declared sizes (413 too_large), 6 archives per minute per user. Every item is re-verified: the mailbox must be readable by the caller and the blob must be an attachment of that message, otherwise 404 and nothing is sent. Duplicate names get (2), (3)…; path separators and control characters are removed from entry names.

Files main
Menu

Theme