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_cursoris opaque, bound to the query (text, mailboxes,threads,tz) — reusing it with another query answers400 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(orYYYY/MM/DD),today(aujourd'hui),yesterday(hier): calendar days in thetzzone.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
{
"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 agroupare OR-ed; groups are AND-ed.before:/after:carrydate(the UTC instant actually compared),larger:/smaller:carrybytes, quoted free text carriesphrase: true.valueis normalised foris:(unread,starred…) andin:(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.qfilters on the file name (case and accents ignored);fromon the sender;after/beforetake the same date values as the query language or an ISO 8601 date;min_size/max_sizeare bytes.- Images embedded in a message body (
cid:, inline) are not listed. download_urlis the existing gateway route/api/jmap/{mailbox}/download/{accountId}/{blobId}/{name}?accept={type}: always served as an attachment with a sandboxing CSP.inline_okis 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.