@rapidmx/web-client 0.21.0 → 0.22.0

package/lib/mail/conversationsApi.ts

@@ -0,0 +1,123 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrapper over `@rapidmx/restapi`'s conversation endpoints (`BaseMessageRoute.conversations()` and
+ * `conversationMessages()`) — the parent rows of a nested, Outlook-style conversation list, and the child rows
+ * one expands into. Conversations are RFC 5322 References/In-Reply-To threads (`Message.conversationId`),
+ * computed fresh on every call — a `ConversationSummary` is never itself persisted.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { Message, MessageListFilter, Recipient } from "./mailApi.js";
+
+export interface ConversationSummary {
+    conversationId: string;
+    /** The most recent message's subject line. */
+    subject: string;
+    /** Every message in this conversation, oldest to newest. */
+    messageUids: string[];
+    /** Every folder (deduped) this conversation has a message in — a conversation can span folders,
+     * e.g. an Inbox message and the Sent Items copy of its reply. */
+    folderUids: string[];
+    messageCount: number;
+    unreadCount: number;
+    /** The most recent message's `receivedDate` — what the list is sorted by (newest first). */
+    latestDate: string;
+    /** Every distinct participant (deduped by address) across every message in the conversation. */
+    participants: Recipient[];
+    hasAttachments: boolean;
+    /** `true` if any message in the conversation is flagged. */
+    flagged: boolean;
+    /** The most recent message's `uid` — what a collapsed conversation row stands for, so it can be opened
+     * without expanding the conversation first. */
+    latestMessageUid: string;
+    /** The most recent message's sender. */
+    latestFrom: Recipient;
+    /** The most recent message's `bodyPreview` — the snippet a collapsed row shows. */
+    latestPreview: string;
+    /** The most recent message's folder. */
+    latestFolderUid: string;
+    /** The iTIP `METHOD` of the calendar file the most recent message carries (`Message.meetingMethod`) - `"REQUEST"`, `"REPLY"`,
+     * `"CANCEL"`, `"PUBLISH"`, `"COUNTER"` or `""`. Absent, or `null` from the server's SQL, when it carries none. Lets a collapsed row mark a
+     * meeting request without opening the conversation. */
+    latestMeetingMethod?: string | null;
+    /** What the reader answered that meeting request with (`Message.meetingResponse`). Absent, or `null`, when unanswered. */
+    latestMeetingResponse?: "accepted" | "tentative" | "declined" | null;
+}
+
+/**
+ * How many of a mailbox's *messages* the server reads, newest first, to build these groups — restapi's
+ * `mail:conversations:scan_limit` default, and also the cap and default for `limit` below. A conversation whose
+ * older messages fall outside that window reports only the part inside it.
+ */
+export const CONVERSATION_SCAN_LIMIT = 500;
+
+export interface ConversationListParams {
+    /** Restricts both the scan and the grouping to one folder — a per-folder conversation view. Without it a
+     * conversation spans every folder in the mailbox. */
+    folderUid?: string;
+    /** The same named filters `listMessages()` takes, applied to the *messages* before they are grouped: so
+     * `unread` yields each conversation's unread messages, and only the conversations that have any. */
+    filter?: MessageListFilter;
+    /** The label filter `listMessages()` takes (`Label.uid`s; a message matching ANY of them), applied at the
+     * same point as `filter` and ANDed with it — so a conversation appears if any of its messages carries any
+     * of these labels, and reports only those messages. At most `MAX_MESSAGE_LABEL_FILTER` of them. */
+    labelUids?: string[];
+    /** Zero-based. */
+    page?: number;
+    /** Capped at `CONVERSATION_SCAN_LIMIT`, which is also the default. */
+    limit?: number;
+}
+
+/** `?mailboxUid=` plus whichever optional params were actually set, each URL-encoded. */
+function conversationQuery(mailboxUid: string, params: Record<string, string | number | undefined>): string {
+    const query = new URLSearchParams({ mailboxUid });
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== "") {
+            query.set(key, String(value));
+        }
+    }
+    return query.toString();
+}
+
+/** Lists a mailbox's conversations, newest activity first. Computed mailbox-wide unless `folderUid` narrows
+ * them — folder scope is a filter here, not part of the endpoint. */
+export function listConversations(
+    mailboxUid: string,
+    params: ConversationListParams = {},
+    client?: ApiClient,
+): Promise<ConversationSummary[]> {
+    const { labelUids, ...rest } = params;
+    // One comma-separated value, as `messageListQuery()` sends it; an empty selection sends no parameter.
+    return withClient(
+        client,
+        `/mail/messages/conversations?${conversationQuery(mailboxUid, { ...rest, labelUids: labelUids?.length ? labelUids.join(",") : undefined })}`,
+    );
+}
+
+/** Paging for `listConversationMessages()`. The server defaults `limit` to 100 and caps it at 500. */
+export interface ConversationMessagesParams {
+    page?: number;
+    limit?: number;
+}
+
+/**
+ * One conversation's messages, oldest first, across every folder in the mailbox — the expanded children of a
+ * conversation row, in one request rather than one per `messageUids` entry.
+ *
+ * `conversationId` is the summary's own `conversationId`, which for a message belonging to no thread is that
+ * message's `uid`; the server resolves either.
+ */
+export function listConversationMessages(
+    mailboxUid: string,
+    conversationId: string,
+    params: ConversationMessagesParams = {},
+    client?: ApiClient,
+): Promise<Message[]> {
+    return withClient(
+        client,
+        `/mail/messages/conversations/${encodeURIComponent(conversationId)}?${conversationQuery(mailboxUid, { ...params })}`,
+    );
+}

package/lib/mail/dataExportApi.ts

@@ -0,0 +1,73 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR data-portability export (`BaseDataExportRoute`, mounted
+ * at `mail/data-export-requests`). `create()` is both self-service (a mailbox owner exports their own
+ * mail) and admin-mediated (a trusted caller may supply an explicit `mailboxUid`) — an ordinary caller's
+ * own mailbox is always used regardless of what they send, only a trusted caller's supplied `mailboxUid`
+ * is honored. Export runs asynchronously (restapi's own `DataExportJob`, not this client) — `create()`
+ * only stages a `pending` request; poll `getExportRequest()`/`listExportRequests()` for `status` to
+ * become `"ready"` (or `"failed"`) before offering the download.
+ */
+import { ApiClient, apiUrl, withClient } from "../util/api.js";
+import { RequestListParams, buildRequestListQuery } from "../util/apiQuery.js";
+
+export type { RequestListParams };
+
+export type DataExportFormat = "json" | "mbox";
+/** `processing` while a worker is building the export (restapi's `DataExportJob` claims `pending` requests). */
+export type DataExportStatus = "pending" | "processing" | "ready" | "failed";
+
+export interface DataExportRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    format: DataExportFormat;
+    status: DataExportStatus;
+    blobKey?: string;
+    errorMessage?: string;
+    /** How many times the server job has claimed this request into `"processing"` (a stalled claim is reclaimed
+     * back to `"pending"` until the job's max attempts, then marked `"failed"`). */
+    processingAttempts?: number;
+}
+
+export interface CreateDataExportRequestInput {
+    format: DataExportFormat;
+    /** Only honored when the caller is a trusted admin — an ordinary caller's own mailbox is always
+     * used, regardless of what (if anything) is supplied here. */
+    mailboxUid?: string;
+}
+
+/** `client`, given by every function below that isn't a plain URL builder, is an explicit `ApiClient` from
+ * `createApiClient()` (e.g. one account of a multi-account app) to call instead of the default global
+ * `apiFetch()` - see `withClient()`'s own doc comment in `util/api.ts`. Omitted (the default), every
+ * function here behaves exactly as before. */
+export function createExportRequest(input: CreateDataExportRequestInput, client?: ApiClient): Promise<DataExportRequest> {
+    return withClient(client, `/mail/data-export-requests`, {
+        method: "POST",
+        body: JSON.stringify(input),
+    });
+}
+
+/** A trusted caller sees every request; anyone else sees only their own (`requestedByUserUid`). Newest
+ * first; `params` pages through them (`limit` capped at 500 server-side). */
+export function listExportRequests(params: RequestListParams = {}, client?: ApiClient): Promise<DataExportRequest[]> {
+    return withClient(client, `/mail/data-export-requests${buildRequestListQuery(params)}`);
+}
+
+export function getExportRequest(uid: string, client?: ApiClient): Promise<DataExportRequest> {
+    return withClient(client, `/mail/data-export-requests/${encodeURIComponent(uid)}`);
+}
+
+/** A plain URL, not a fetch wrapper — the server streams the export's raw bytes back with its own
+ * `content-disposition: attachment` header, so a caller renders this directly as `<a href={...}>`
+ * (the browser's own native download, no JS fetch/blob needed) — same pattern `mailApi.ts`'s
+ * `attachmentContentUrl()` already establishes. 404s until `status === "ready"`. */
+export function exportRequestDownloadUrl(uid: string): string {
+    return apiUrl(`/mail/data-export-requests/${encodeURIComponent(uid)}/download`);
+}

package/lib/mail/directoryApi.ts

@@ -0,0 +1,161 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `BaseDirectoryRoute` - recipient suggestions for compose. `GET
+ * /mail/directory` searches the server's mailboxes (people, shared mailboxes, rooms and equipment) and distribution
+ * lists; `GET /mail/directory/contacts` searches the caller's own contacts. Both match every word of the query against
+ * the start of a name word or of an address, and return only a display name, an address and a kind.
+ */
+import { ApiClient, ApiRequestError, withClient } from "../util/api.js";
+
+/** What a suggestion names. `"contact"` comes from the caller's contacts, everything else from the server directory. */
+export type RecipientSuggestionKind = "user" | "shared" | "room" | "equipment" | "list" | "contact";
+
+export interface RecipientSuggestion {
+    displayName: string;
+    address: string;
+    kind: RecipientSuggestionKind;
+}
+
+/** The shortest trimmed query the server searches for - shorter ones resolve to `[]` without a request. */
+export const RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH = 2;
+/** The longest query the server accepts; longer ones are cut to this length. */
+export const RECIPIENT_SUGGESTION_MAX_QUERY_LENGTH = 100;
+/** The server's own default and cap for `limit`. */
+export const RECIPIENT_SUGGESTION_DEFAULT_LIMIT = 8;
+export const RECIPIENT_SUGGESTION_MAX_LIMIT = 20;
+
+export interface RecipientSuggestionOptions {
+    /** At most this many entries (the server caps it at `RECIPIENT_SUGGESTION_MAX_LIMIT`). */
+    limit?: number;
+    /** Aborts the request, rejecting with the fetch's `AbortError`. */
+    signal?: AbortSignal;
+}
+
+export interface ContactSuggestionOptions extends RecipientSuggestionOptions {
+    /** Also search this mailbox's contacts (e.g. the shared mailbox being composed from) when the caller may read it.
+     * The caller's own mailboxes are always searched. */
+    mailboxUid?: string;
+}
+
+/** The trimmed query to send, or `undefined` when it's too short to search. */
+function normalizeQuery(query: string): string | undefined {
+    const trimmed = query.trim().slice(0, RECIPIENT_SUGGESTION_MAX_QUERY_LENGTH).trim();
+    return trimmed.length >= RECIPIENT_SUGGESTION_MIN_QUERY_LENGTH ? trimmed : undefined;
+}
+
+/** Keeps only well-formed entries of a response. */
+function wellFormed(body: unknown): RecipientSuggestion[] {
+    return Array.isArray(body)
+        ? body
+              .filter((entry) => entry && typeof entry.address === "string" && entry.address.length > 0)
+              .map((entry) => ({
+                  displayName: typeof entry.displayName === "string" ? entry.displayName : "",
+                  address: entry.address,
+                  kind: entry.kind,
+              }))
+        : [];
+}
+
+async function fetchSuggestions(
+    path: string,
+    query: string,
+    params: Record<string, string | undefined>,
+    signal?: AbortSignal,
+    client?: ApiClient,
+): Promise<RecipientSuggestion[]> {
+    const q = normalizeQuery(query);
+    if (q === undefined) {
+        return [];
+    }
+    const search = new URLSearchParams({ q });
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+            search.set(key, value);
+        }
+    }
+    return wellFormed(await withClient(client, `${path}?${search.toString()}`, signal ? { signal } : {}));
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+
+/** Searches the server directory. Rejects with a 403 `ApiRequestError` for a caller without a mailbox on the server,
+ * and a 429 one when the caller searches too often. */
+export function searchDirectory(query: string, options: RecipientSuggestionOptions = {}, client?: ApiClient): Promise<RecipientSuggestion[]> {
+    return fetchSuggestions("/mail/directory", query, { limit: options.limit?.toString() }, options.signal, client);
+}
+
+/** Searches the caller's contacts (every address of a contact whose name matches, or the addresses that match). */
+export function searchContactSuggestions(
+    query: string,
+    options: ContactSuggestionOptions = {},
+    client?: ApiClient,
+): Promise<RecipientSuggestion[]> {
+    return fetchSuggestions(
+        "/mail/directory/contacts",
+        query,
+        { limit: options.limit?.toString(), mailboxUid: options.mailboxUid },
+        options.signal,
+        client,
+    );
+}
+
+/** Contacts first, then directory entries, without repeating an address (compared case-insensitively; the first
+ * occurrence wins), at most `limit`. */
+export function mergeRecipientSuggestions(
+    contacts: RecipientSuggestion[],
+    directory: RecipientSuggestion[],
+    limit: number = RECIPIENT_SUGGESTION_DEFAULT_LIMIT,
+): RecipientSuggestion[] {
+    const seen = new Set<string>();
+    const result: RecipientSuggestion[] = [];
+    for (const entry of [...contacts, ...directory]) {
+        const key = entry.address.trim().toLowerCase();
+        if (result.length >= limit) {
+            break;
+        }
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(entry);
+        }
+    }
+    return result;
+}
+
+function isAbort(error: unknown): boolean {
+    return (error as { name?: string } | undefined)?.name === "AbortError";
+}
+
+/**
+ * Contacts and directory suggestions for `query`, merged by `mergeRecipientSuggestions()`. Either source failing (a 403
+ * directory for a caller with no mailbox here, a 429, a network error) still returns the other's entries; only when
+ * both fail does this reject, with the contacts error. An aborted `signal` always rejects with the `AbortError`.
+ */
+export async function fetchRecipientSuggestions(
+    query: string,
+    options: ContactSuggestionOptions = {},
+    client?: ApiClient,
+): Promise<RecipientSuggestion[]> {
+    const limit = options.limit ?? RECIPIENT_SUGGESTION_DEFAULT_LIMIT;
+    const [contacts, directory] = await Promise.allSettled([
+        searchContactSuggestions(query, { ...options, limit }, client),
+        searchDirectory(query, { limit, signal: options.signal }, client),
+    ]);
+    for (const outcome of [contacts, directory]) {
+        if (outcome.status === "rejected" && isAbort(outcome.reason)) {
+            throw outcome.reason;
+        }
+    }
+    if (contacts.status === "rejected" && directory.status === "rejected") {
+        throw contacts.reason instanceof Error ? contacts.reason : new ApiRequestError("Suggestions couldn't be loaded.", 0);
+    }
+    return mergeRecipientSuggestions(
+        contacts.status === "fulfilled" ? contacts.value : [],
+        directory.status === "fulfilled" ? directory.value : [],
+        limit,
+    );
+}

package/lib/mail/erasureRequestApi.ts

@@ -0,0 +1,71 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s GDPR Article 17 ("right to erasure") request
+ * (`BaseDataSubjectErasureRequestRoute`, mounted at `mail/erasure-requests`). Unlike
+ * `dataExportApi.ts`/`mailboxImportApi.ts`, `create()` is self-service only — there is no
+ * admin-on-behalf-of path, and no `mailboxUid` parameter to override; it is always the caller's own
+ * mailbox. `approve()`/`deny()` are trusted-admin-only server-side. The actual destructive cascade is
+ * asynchronous (restapi's own `ErasureExecutionJob`, not this client) and irreversible once it runs — an
+ * approved request 409s during approval, and is retried indefinitely (never failed) by the job itself,
+ * while the target mailbox is a custodian on an active legal hold.
+ */
+import { ApiClient, withClient } from "../util/api.js";
+import { RequestListParams, buildRequestListQuery } from "../util/apiQuery.js";
+
+export type { RequestListParams };
+
+export type DataSubjectErasureStatus = "pending" | "approved" | "in_progress" | "denied" | "completed";
+
+export interface DataSubjectErasureRequest {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    requestedByUserUid: string;
+    status: DataSubjectErasureStatus;
+    reviewedByUserUid?: string;
+    /** Only ever set by `denyErasureRequest()` — never required or meaningful for an approval. */
+    reason?: string;
+    /** Set once `status === "completed"` — a single aggregate count, not a per-row manifest. */
+    purgedCount?: number;
+    /** Set when an administrator filed this request for the data a deleted mailbox left behind (see `admin/leftoverMailboxApi.ts`) - it
+     * was approved when filed, and never removes a mailbox. */
+    leftoverOnly?: boolean;
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+
+/** Always the caller's own mailbox — 409s if a `pending` request for it already exists. */
+export function createErasureRequest(client?: ApiClient): Promise<DataSubjectErasureRequest> {
+    return withClient(client, `/mail/erasure-requests`, { method: "POST" });
+}
+
+/** A trusted caller sees every request; anyone else sees only their own (`requestedByUserUid`). Newest
+ * first; `params` pages through them (`limit` capped at 500 server-side). */
+export function listErasureRequests(params: RequestListParams = {}, client?: ApiClient): Promise<DataSubjectErasureRequest[]> {
+    return withClient(client, `/mail/erasure-requests${buildRequestListQuery(params)}`);
+}
+
+export function getErasureRequest(uid: string, client?: ApiClient): Promise<DataSubjectErasureRequest> {
+    return withClient(client, `/mail/erasure-requests/${encodeURIComponent(uid)}`);
+}
+
+/** 409s if the mailbox is a custodian on an active legal hold, naming the blocking Matter uid(s) in the
+ * error message — surface this as-is, the same "server's own message wins" convention used everywhere
+ * else in this codebase for a destructive-action error. */
+export function approveErasureRequest(uid: string, client?: ApiClient): Promise<DataSubjectErasureRequest> {
+    return withClient(client, `/mail/erasure-requests/${encodeURIComponent(uid)}/approve`, { method: "POST" });
+}
+
+export function denyErasureRequest(uid: string, reason: string, client?: ApiClient): Promise<DataSubjectErasureRequest> {
+    return withClient(client, `/mail/erasure-requests/${encodeURIComponent(uid)}/deny`, {
+        method: "POST",
+        body: JSON.stringify({ reason }),
+    });
+}

package/lib/mail/flaggedMessages.ts

@@ -0,0 +1,80 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Backs Tasks' "Flagged email" smart-list (an Outlook To-Do concept: flagged *Messages*, not Tasks,
+ * surfaced into the Tasks app).
+ *
+ * The server now does the filtering: `listMessages({ filter: "flagged" })` is an indexed database predicate on
+ * the denormalized `Message.flagged` mirror (`flags` itself is one JSON column, which is why this used to read
+ * every message in the mailbox and filter in the browser). What is still client-side is the fan-out: a message
+ * list is folder-scoped, and "every flagged message in this mailbox" spans every mail folder, so this still
+ * makes one paged call per folder and merges the results. The client-side `flags.flagged` check below is kept
+ * as a cheap guard for a row written before the mirror existed, not as the filter.
+ */
+import { Folder, Message, listFolders, listMessages } from "./mailApi.js";
+import { ApiClient } from "../util/api.js";
+
+/** Folder types that actually hold `Message` records — mirrors `MailShell.tsx`'s own `MAIL_FOLDER_TYPES`
+ * allowlist (kept as a separate local copy rather than a shared export, since the two call sites have no
+ * other coupling and this list is small/stable). */
+const MAIL_FOLDER_TYPES = new Set(["inbox", "drafts", "outbox", "sent_items", "junk", "deleted_items", "archive", "user"]);
+
+/** The server's own per-request `limit` cap - a page shorter than this is the folder's last one. */
+const PAGE_SIZE = 500;
+
+/** Hard cap on pages read per folder (50,000 messages) - guards against paging forever should a server
+ * ignore `page` and keep returning full pages. */
+export const FLAGGED_MAX_PAGES_PER_FOLDER = 100;
+
+/** How many folders are paged through at once, bounding the request burst on a mailbox with many folders. */
+export const FLAGGED_FOLDER_CONCURRENCY = 4;
+
+/** Every flagged message in one folder, paging through `listMessages()` until a short page. Only flagged
+ * messages are kept (a large folder's unflagged pages are dropped as they arrive). Stops early at
+ * `FLAGGED_MAX_PAGES_PER_FOLDER`, or when a full page brings no message not already seen (a server
+ * ignoring `page` and returning the same page again). */
+async function listFlaggedInFolder(folderUid: string, seen: Set<string>, client?: ApiClient): Promise<Message[]> {
+    const flagged: Message[] = [];
+    const seenInFolder = new Set<string>();
+    for (let page = 0; page < FLAGGED_MAX_PAGES_PER_FOLDER; page += 1) {
+        const batch = await listMessages(folderUid, { limit: PAGE_SIZE, page, filter: "flagged" }, client);
+        let fresh = 0;
+        for (const message of batch) {
+            if (seenInFolder.has(message.uid)) {
+                continue;
+            }
+            seenInFolder.add(message.uid);
+            fresh += 1;
+            // Deduplicated across folders too: a message moved mid-listing can appear in two folders' pages.
+            if (message.flags.flagged && !seen.has(message.uid)) {
+                seen.add(message.uid);
+                flagged.push(message);
+            }
+        }
+        if (batch.length < PAGE_SIZE || fresh === 0) {
+            break;
+        }
+    }
+    return flagged;
+}
+
+/** Lists every flagged message across all of a mailbox's mail folders (not just Inbox), newest first, each
+ * message at most once. `client`, when given, is threaded through to every underlying `listFolders()`/
+ * `listMessages()` call (see `useApiClient()`'s own doc comment) - omitted, this behaves exactly as before. */
+export async function listFlaggedMessages(mailboxUid: string, client?: ApiClient): Promise<Message[]> {
+    const folders: Folder[] = await listFolders(mailboxUid, client);
+    const mailFolders = folders.filter((f) => MAIL_FOLDER_TYPES.has(f.type));
+    const seen = new Set<string>();
+    const perFolder: Message[][] = [];
+    let next = 0;
+    async function worker(): Promise<void> {
+        while (next < mailFolders.length) {
+            const index = next++;
+            perFolder[index] = await listFlaggedInFolder(mailFolders[index].uid, seen, client);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(FLAGGED_FOLDER_CONCURRENCY, mailFolders.length) }, () => worker()));
+    return perFolder.flat().sort((a, b) => new Date(b.receivedDate).getTime() - new Date(a.receivedDate).getTime());
+}

package/lib/mail/focusedInboxOverridesApi.ts

@@ -0,0 +1,64 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `FocusedInboxOverride` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — the standing "always classify mail from this sender as Focused/Other"
+ * rules `BaseMessageRoute.classify()` (see `classifyMessage()` in `mailApi.ts`) upserts when a caller sets
+ * `applyToSender: true`. This file lets a Settings page list/remove those rules directly, and add one by
+ * hand without first receiving a matching message.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+import { MessageClassification } from "./mailApi.js";
+
+export type { ListParams };
+
+export interface FocusedInboxOverride {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    senderAddress: string;
+    classifyAs: MessageClassification;
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function listFocusedInboxOverrides(mailboxUid: string, params: ListParams = {}, client?: ApiClient): Promise<FocusedInboxOverride[]> {
+    return withClient(client, `/mail/focused-inbox-overrides?${buildQuery(params, { mailboxUid })}`);
+}
+
+export interface CreateFocusedInboxOverrideInput {
+    mailboxUid: string;
+    senderAddress: string;
+    classifyAs: MessageClassification;
+}
+
+export function createFocusedInboxOverride(input: CreateFocusedInboxOverrideInput, client?: ApiClient): Promise<FocusedInboxOverride> {
+    return withClient(client, "/mail/focused-inbox-overrides", {
+        method: "POST",
+        body: JSON.stringify(input),
+    });
+}
+
+export interface UpdateFocusedInboxOverrideInput {
+    uid: string;
+    version: number;
+    classifyAs: MessageClassification;
+}
+
+export function updateFocusedInboxOverride(input: UpdateFocusedInboxOverrideInput, client?: ApiClient): Promise<FocusedInboxOverride> {
+    return withClient(client, `/mail/focused-inbox-overrides/${encodeURIComponent(input.uid)}`, {
+        method: "PUT",
+        body: JSON.stringify(input),
+    });
+}
+
+export function deleteFocusedInboxOverride(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/focused-inbox-overrides/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}

package/lib/mail/labelsApi.ts

@@ -0,0 +1,71 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Typed wrappers over `@rapidmx/restapi`'s `Label` CRUD route (`BaseScopedChildRoute`,
+ * `scopeProperty: "mailboxUid"`) — mailbox-scoped, same pattern as `mailSignaturesApi.ts`. A label is
+ * applied to a message by setting `Message.labelUids` directly (an ordinary field, not read-only - see
+ * `mailApi.ts#setMessageLabels()`), the same way `MailFilterActionType.APPLY_LABEL` does it
+ * automatically for inbound mail; there is no separate "assign" endpoint.
+ */
+
+import { ApiClient, withClient } from "../util/api.js";
+import { ListParams, buildQuery } from "../util/apiQuery.js";
+
+export type { ListParams };
+
+export interface Label {
+    uid: string;
+    version: number;
+    dateCreated: string;
+    dateModified: string;
+    mailboxUid: string;
+    name: string;
+    /** An optional hex-ish color hint (same loose convention as `Note.color`) - restapi doesn't
+     * validate its shape. */
+    color?: string;
+}
+
+/** `client`, given by every function below, is an explicit `ApiClient` from `createApiClient()` (e.g. one
+ * account of a multi-account app) to call instead of the default global `apiFetch()` - see `withClient()`'s
+ * own doc comment in `util/api.ts`. Omitted (the default), every function here behaves exactly as before. */
+export function listLabels(mailboxUid: string, params: ListParams = {}, client?: ApiClient): Promise<Label[]> {
+    return withClient(client, `/mail/labels?${buildQuery(params, { mailboxUid })}`);
+}
+
+export function getLabel(uid: string, client?: ApiClient): Promise<Label> {
+    return withClient(client, `/mail/labels/${encodeURIComponent(uid)}`);
+}
+
+export interface CreateLabelInput {
+    mailboxUid: string;
+    name: string;
+    color?: string;
+}
+
+export function createLabel(input: CreateLabelInput, client?: ApiClient): Promise<Label> {
+    return withClient(client, "/mail/labels", { method: "POST", body: JSON.stringify(input) });
+}
+
+export interface UpdateLabelInput {
+    uid: string;
+    version: number;
+    name?: string;
+    color?: string;
+}
+
+export function updateLabel(input: UpdateLabelInput, client?: ApiClient): Promise<Label> {
+    return withClient(client, `/mail/labels/${encodeURIComponent(input.uid)}`, { method: "PUT", body: JSON.stringify(input) });
+}
+
+/**
+ * Deleting a label also strips its uid from every message's `labelUids` in this mailbox
+ * (`BaseLabelRoute.cleanUpDeletedLabel()`, a synchronous full-mailbox scan server-side) - the client
+ * has no separate cleanup step to perform, but a caller with an already-loaded message list should
+ * still drop the deleted uid from any locally-cached `labelUids` itself, since this call doesn't return
+ * the affected messages.
+ */
+export function deleteLabel(uid: string, version: number, client?: ApiClient): Promise<void> {
+    return withClient(client, `/mail/labels/${encodeURIComponent(uid)}?version=${version}`, { method: "DELETE" });
+}