Repository Public
1# SP Mail Next — search query language23One 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.45## Routes67| Route | Purpose |8|---|---|9| `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 } }` |10| `POST /api/next/search/parse { q, tz? }` | Parsed form only (chips, validation while typing). Never fails on bad input: defects are in `errors` |11| `GET /api/next/attachments?…` | Attachment gallery (see below) |12| `POST /api/next/attachments/zip` | Streams a ZIP of selected attachments |1314All routes need a device session (web cookie or native bearer), never an API key.1516`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[] }`.1718- `mailboxes`: `all` (default) or a comma-separated list of mailbox ids. A mailbox of another user → `404`.19- `limit`: 1–100 (default 50).20- `threads=1`: one result per thread and mailbox (the newest matching message).21- `tz`: IANA time zone used for calendar dates (`before:2026-01-15`, `today`). Unknown or absent = UTC.22- 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.2324## Terms2526A 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.2728| Operator | Synonyms | Meaning | JMAP |29|---|---|---|---|30| *free word* | | Anywhere in the message (headers, body) | `text` |31| `"exact phrase"` | | Phrase search | `text` (quoted) |32| `from:` | `de:` `expediteur:` `sender:` | Sender name or address | `from` |33| `to:` | `à:` `a:` `pour:` `destinataire:` | To recipient | `to` |34| `cc:` | | Cc recipient | `cc` |35| `bcc:` | `cci:` | Bcc recipient (sent mail) | `bcc` |36| `subject:` | `sujet:` `objet:` | Subject | `subject` |37| `body:` | `corps:` `texte:` `contenu:` | Body only | `body` |38| `has:attachment` | `avec:pj` `has:pièce` `avec:fichier` `contient:…` | Has at least one attachment | `hasAttachment` |39| `is:unread` / `is:read` | `est:non-lu` `est:lu` `is:unseen` `is:seen` | Read state | `notKeyword` / `hasKeyword` `$seen` |40| `is:starred` | `is:flagged` `est:suivi` `est:important` | Starred | `$flagged` |41| `is:pinned` | `est:épinglé` | Pinned | `$pinned` |42| `is:snoozed` | `est:reporté` | Snoozed | `$snoozed` |43| `is:followup` | `est:relance` `est:à-suivre` | Follow-up flag | `$followup` |44| `is:answered` `is:forwarded` `is:draft` | `est:répondu` `est:transféré` `est:brouillon` | | `$answered` `$forwarded` `$draft` |45| `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_…` |46| `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` |47| `before:` | `avant:` `older_than:` | Received before (see dates) | `before` |48| `after:` | `après:` `since:` `depuis:` `newer_than:` | Received after | `after` |49| `larger:` | `bigger:` `plusgrand:` | Size ≥ value | `minSize` |50| `smaller:` | `pluspetit:` | Size ≤ value | `maxSize` |51| `filename:` | `fichier:` `file:` `nom:` | An attachment name contains the value (case and accents ignored) | `hasAttachment` + server-side check of the attachment names |5253An 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.5455### Dates5657- `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.58- 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.5960### Sizes6162A number with an optional unit, multiples of 1024: `500`, `10k` (`10kb`, `10ko`), `5m` (`5mb`, `5mo`), `1g`. Decimals are accepted (`1.5m`).6364### Default scope6566Without 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.6768## Parsed form and errors6970```json71{72 "terms": [{ "op": "from", "value": "alice", "negated": false, "raw": "from:alice", "start": 0, "end": 10, "group": 0 }],73 "filters": { "operator": "AND", "conditions": [{ "from": "alice" }, { "notIn": ["trash", "junk"] }] },74 "errors": []75}76```7778- `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`…).79- `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"] }`).80- `errors`: `{ token, start, end, code, message }`. A token in error is ignored; the rest of the query still runs. The parser never throws.8182| Code | Cause |83|---|---|84| `empty_value` | `from:` with nothing after the colon |85| `invalid_value` | unknown `is:` state, or `has:` other than `attachment` |86| `invalid_date` | not a date, `today`/`yesterday` or a duration |87| `invalid_size` | not a size |88| `dangling_or` | `OR` not standing between two terms |89| `filename_in_or` | `filename:` used as a branch of an `OR` (it is then treated as `has:attachment`) |90| `unknown_label` | no label has that name — the term matches nothing |91| `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) |92| `query_too_long` / `too_many_terms` | more than 1000 characters / 50 terms; the rest is ignored |9394## Attachments9596`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.9798`Attachment = { mailbox_id, email_id, thread_id, blob_id, part_id, name, type, size, kind, from, subject, received_at, download_url, inline_ok }`.99100- `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.101- `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.102- Images embedded in a message body (`cid:`, inline) are not listed.103- `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).104105`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.106