@open-workspace/email 0.1.0 → 0.2.0

package/alchemy.ts

@@ -28,6 +28,8 @@ export type EmailInfraProps = {
   bucketName?: string;
   /** Queue names default to `<name>-<role>`; set to keep existing queues. */
   queuePrefix?: string;
+  /** Name of an existing Office preview container application to adopt. */
+  containerName?: string;
 };
 
 /**
@@ -63,6 +65,7 @@ export function Email(props: EmailInfraProps = {}): (name: string) => WorkspaceM
         MAILBOX: Cloudflare.DurableObject("MAILBOX", { className: "MailboxDO" }),
         OFFICE_PREVIEW_CONTAINER: Cloudflare.Container("OfficePreview", {
           className: "OfficePreviewContainer",
+          ...(props.containerName ? { name: props.containerName } : {}),
           context: join(packageDir, "containers", "office-preview"),
           maxInstances: 2,
         }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-workspace/email",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Team mail for OpenWorkspace: personal and shared inboxes, mailing lists, previews, safety, and AI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,7 +20,7 @@
     "db:generate": "drizzle-kit generate && drizzle-kit generate --config=drizzle.mailbox.config.ts && bun scripts/embed-mailbox-migrations.ts"
   },
   "peerDependencies": {
-    "@open-workspace/core": "0.1.0",
+    "@open-workspace/core": "0.2.0",
     "alchemy": "2.0.0-beta.84",
     "@alchemy.run/cloudflare": "2.0.0-beta.84",
     "effect": "4.0.7"
@@ -42,7 +42,7 @@
     "@base-ui/react": "1.7.0",
     "@effect/platform-bun": "4.0.7",
     "@effect/platform-node": "4.0.7",
-    "@open-workspace/core": "0.1.0",
+    "@open-workspace/core": "0.2.0",
     "@simplewebauthn/browser": "13.3.0",
     "@tanstack/react-query": "5.102.8",
     "@tiptap/extension-image": "3.30.5",

package/worker/jmap/methods.ts

@@ -0,0 +1,678 @@
+import { mailboxStub } from "../mailbox";
+import type { Email } from "../mailbox/schema";
+import type { JmapEmailFilter, JmapMailboxRow } from "../mailbox/jmap-store";
+import { submitOutgoing } from "../mail/outbound-service";
+
+const CORE = "urn:ietf:params:jmap:core";
+const MAX_OBJECTS = 500;
+
+export type JmapAccount = {
+  id: string;
+  address: string;
+  displayName: string;
+  ownerUserId: string | null;
+  isPrimary: boolean;
+  canSend: boolean;
+  isPersonal: boolean;
+};
+
+export type JmapContext = {
+  env: Env;
+  user: { id: string; name: string };
+  accounts: JmapAccount[];
+  requestUrl: string;
+  defer: (task: Promise<unknown>) => void;
+};
+
+type Args = Record<string, unknown>;
+type Invocation = [string, Args, string];
+
+/** A request-level error (RFC 8620 §3.6.1), answered as a problem document. */
+export class JmapError extends Error {
+  constructor(readonly type: string, message: string) {
+    super(message);
+  }
+}
+
+/** A method-level error (RFC 8620 §3.6.2), answered in place of the method's response. */
+class MethodError extends Error {
+  constructor(readonly type: string, message?: string) {
+    super(message ?? type);
+  }
+}
+
+/** A draft from Email/set create; it lives only for the request that sends it. */
+type Draft = {
+  accountId: string;
+  to: string[];
+  cc: string[];
+  bcc: string[];
+  subject: string;
+  bodyText: string;
+  bodyHtml?: string;
+};
+
+type RequestState = {
+  context: JmapContext;
+  responses: Invocation[];
+  createdIds: Record<string, string>;
+  drafts: Map<string, Draft>;
+  /** Responses a method adds after its own, e.g. an implicit Email/set. */
+  after: Invocation[];
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ---------------------------------------------------------------- references
+
+/** RFC 8620 §3.7: a JSON Pointer where `*` maps over an array. */
+function evaluatePointer(value: unknown, path: string): unknown {
+  if (path === "") return value;
+  const [head, ...rest] = path.slice(1).split("/").map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"));
+  const tail = rest.length ? `/${rest.join("/")}` : "";
+  if (head === "*" && Array.isArray(value)) {
+    return value.flatMap((item) => {
+      const result = evaluatePointer(item, tail);
+      return Array.isArray(result) ? result : [result];
+    });
+  }
+  if (Array.isArray(value) && /^\d+$/u.test(head!)) return evaluatePointer(value[Number(head)], tail);
+  if (isRecord(value) && head! in value) return evaluatePointer(value[head!], tail);
+  throw new MethodError("invalidResultReference", `Path ${path} does not resolve`);
+}
+
+function resolveReferences(state: RequestState, args: Args): Args {
+  const resolved: Args = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!key.startsWith("#")) {
+      resolved[key] = value;
+      continue;
+    }
+    const name = key.slice(1);
+    if (name in args) throw new MethodError("invalidArguments", `Both ${name} and #${name} given`);
+    if (!isRecord(value) || typeof value.resultOf !== "string" || typeof value.name !== "string" || typeof value.path !== "string") {
+      throw new MethodError("invalidResultReference");
+    }
+    const source = state.responses.find(([method, , callId]) => callId === value.resultOf && method === value.name);
+    if (!source) throw new MethodError("invalidResultReference", `No ${value.name} result for ${value.resultOf}`);
+    resolved[name] = evaluatePointer(source[1], value.path);
+  }
+  return resolved;
+}
+
+// ------------------------------------------------------------------ helpers
+
+function account(state: RequestState, args: Args) {
+  const found = state.context.accounts.find((item) => item.id === args.accountId);
+  if (!found) throw new MethodError("accountNotFound");
+  return found;
+}
+
+function stringIds(value: unknown, name = "ids") {
+  if (!Array.isArray(value) || value.some((id) => typeof id !== "string")) {
+    throw new MethodError("invalidArguments", `${name} must be a list of ids`);
+  }
+  if (value.length > MAX_OBJECTS) throw new MethodError("requestTooLarge");
+  return value as string[];
+}
+
+function pick<T extends Record<string, unknown>>(object: T, properties: unknown) {
+  if (!Array.isArray(properties)) return object;
+  return Object.fromEntries(Object.entries(object).filter(([key]) => key === "id" || properties.includes(key)));
+}
+
+/** We cannot list changes, only say whether anything changed. */
+function changes(accountId: string, sinceState: unknown, state: string) {
+  if (sinceState !== state) throw new MethodError("cannotCalculateChanges");
+  return { accountId, oldState: state, newState: state, hasMoreChanges: false, created: [], updated: [], destroyed: [] };
+}
+
+const addresses = (list: Array<{ address: string; name?: string | null }> | null | undefined) =>
+  list?.length ? list.map((item) => ({ name: item.name || null, email: item.address })) : null;
+
+// ------------------------------------------------------------------ mailbox
+
+function mailboxObject(row: JmapMailboxRow, canSend: boolean) {
+  return {
+    id: row.id,
+    name: row.name,
+    parentId: null,
+    role: row.role,
+    sortOrder: row.sortOrder,
+    totalEmails: row.totalEmails,
+    unreadEmails: row.unreadEmails,
+    totalThreads: row.totalThreads,
+    unreadThreads: row.unreadThreads,
+    myRights: {
+      mayReadItems: true,
+      mayAddItems: row.role !== "sent",
+      mayRemoveItems: true,
+      maySetSeen: true,
+      maySetKeywords: false,
+      mayCreateChild: false,
+      mayRename: false,
+      mayDelete: false,
+      maySubmit: canSend,
+    },
+    isSubscribed: true,
+  };
+}
+
+async function mailboxGet(state: RequestState, args: Args) {
+  const owner = account(state, args);
+  const { state: mailboxState, mailboxes } = await mailboxStub(state.context.env, owner.id).jmapMailboxes(state.context.user.id);
+  const ids = args.ids == null ? mailboxes.map((row) => row.id) : stringIds(args.ids);
+  const byId = new Map(mailboxes.map((row) => [row.id, row]));
+  return {
+    accountId: owner.id,
+    state: mailboxState,
+    list: ids.flatMap((id) => {
+      const row = byId.get(id);
+      return row ? [pick(mailboxObject(row, owner.canSend), args.properties)] : [];
+    }),
+    notFound: ids.filter((id) => !byId.has(id)),
+  };
+}
+
+async function mailboxQuery(state: RequestState, args: Args) {
+  const owner = account(state, args);
+  const { state: mailboxState, mailboxes } = await mailboxStub(state.context.env, owner.id).jmapMailboxes(state.context.user.id);
+  const filter = isRecord(args.filter) ? args.filter : {};
+  const ids = mailboxes
+    .filter((row) => !("role" in filter) || row.role === filter.role)
+    .filter((row) => typeof filter.name !== "string" || row.name.toLowerCase().includes(filter.name.toLowerCase()))
+    .map((row) => row.id);
+  return { accountId: owner.id, queryState: mailboxState, canCalculateChanges: false, position: 0, ids, total: ids.length };
+}
+
+// -------------------------------------------------------------------- email
+
+function emailFilter(value: unknown): JmapEmailFilter {
+  if (value == null) return {};
+  if (!isRecord(value)) throw new MethodError("unsupportedFilter");
+  if ("operator" in value) {
+    if (value.operator !== "AND" || !Array.isArray(value.conditions)) {
+      throw new MethodError("unsupportedFilter", "Only AND filters are supported");
+    }
+    return Object.assign({}, ...value.conditions.map(emailFilter));
+  }
+  const supported = ["inMailbox", "inMailboxOtherThan", "before", "after", "text", "from", "to", "subject", "hasKeyword", "notKeyword", "hasAttachment"];
+  const unknown = Object.keys(value).filter((key) => !supported.includes(key));
+  if (unknown.length) throw new MethodError("unsupportedFilter", `Unsupported filter: ${unknown.join(", ")}`);
+  for (const keyword of [value.hasKeyword, value.notKeyword]) {
+    if (keyword !== undefined && keyword !== "$seen") {
+      throw new MethodError("unsupportedFilter", "Only the $seen keyword is supported");
+    }
+  }
+  return {
+    ...(typeof value.inMailbox === "string" ? { inMailbox: value.inMailbox } : {}),
+    ...(Array.isArray(value.inMailboxOtherThan) ? { inMailboxOtherThan: value.inMailboxOtherThan.map(String) } : {}),
+    ...(typeof value.before === "string" ? { before: Date.parse(value.before) } : {}),
+    ...(typeof value.after === "string" ? { after: Date.parse(value.after) } : {}),
+    ...(typeof value.text === "string" ? { text: value.text } : {}),
+    ...(typeof value.from === "string" ? { from: value.from } : {}),
+    ...(typeof value.to === "string" ? { to: value.to } : {}),
+    ...(typeof value.subject === "string" ? { subject: value.subject } : {}),
+    ...(typeof value.hasKeyword === "string" ? { hasKeyword: value.hasKeyword } : {}),
+    ...(typeof value.notKeyword === "string" ? { notKeyword: value.notKeyword } : {}),
+    ...(typeof value.hasAttachment === "boolean" ? { hasAttachment: value.hasAttachment } : {}),
+  };
+}
+
+async function emailQuery(state: RequestState, args: Args) {
+  const owner = account(state, args);
+  const sort = Array.isArray(args.sort) ? args.sort : [];
+  for (const comparator of sort) {
+    if (!isRecord(comparator) || !["receivedAt", "sentAt"].includes(String(comparator.property))) {
+      throw new MethodError("unsupportedSort", "Emails sort by receivedAt or sentAt");
+    }
+  }
+  const ascending = isRecord(sort[0]) && sort[0].isAscending === true;
+  const position = Math.max(0, Number(args.position ?? 0) || 0);
+  const limit = Math.min(MAX_OBJECTS, Math.max(0, Number(args.limit ?? 100) || 100));
+  const result = await mailboxStub(state.context.env, owner.id).jmapQueryEmails({
+    userId: state.context.user.id,
+    filter: emailFilter(args.filter),
+    ascending,
+    position,
+    limit,
+    collapseThreads: args.collapseThreads === true,
+  });
+  return {
+    accountId: owner.id,
+    queryState: result.state,
+    canCalculateChanges: false,
+    position,
+    ids: result.ids,
+    total: result.total,
+    limit,
+  };
+}
+
+const defaultEmailProperties = [
+  "id", "blobId", "threadId", "mailboxIds", "keywords", "size", "receivedAt", "messageId",
+  "inReplyTo", "references", "sender", "from", "to", "cc", "bcc", "replyTo", "subject",
+  "sentAt", "hasAttachment", "preview", "bodyValues", "textBody", "htmlBody", "attachments",
+];
+
+async function emailObject(
+  env: Env,
+  row: { email: Email; mailboxId: string; seen: boolean },
+  args: Args,
+) {
+  const { email } = row;
+  const raw = `raw~${email.id}`;
+  const textBody = [{
+    partId: "text", blobId: raw, size: email.bodyText?.length ?? 0, name: null,
+    type: "text/plain", charset: "utf-8", disposition: null, cid: null,
+  }];
+  const htmlBody = email.bodyHtmlR2Key
+    ? [{ partId: "html", blobId: raw, size: 0, name: null, type: "text/html", charset: "utf-8", disposition: null, cid: null }]
+    : textBody;
+  const attachments = email.attachmentsJson.map((attachment) => ({
+    partId: `att-${attachment.id}`,
+    blobId: `att~${email.id}~${attachment.id}`,
+    size: attachment.size,
+    name: attachment.filename,
+    type: attachment.contentType,
+    charset: null,
+    disposition: attachment.disposition,
+    cid: attachment.contentId,
+  }));
+  const properties = Array.isArray(args.properties) ? args.properties as string[] : defaultEmailProperties;
+  const maxBytes = Number(args.maxBodyValueBytes ?? 0) || 0;
+  const bodyValue = (value: string) => ({
+    value: maxBytes && value.length > maxBytes ? value.slice(0, maxBytes) : value,
+    isEncodingProblem: false,
+    isTruncated: Boolean(maxBytes && value.length > maxBytes),
+  });
+  const bodyValues: Record<string, ReturnType<typeof bodyValue>> = {};
+  if (properties.includes("bodyValues")) {
+    const wantText = args.fetchTextBodyValues === true || args.fetchAllBodyValues === true;
+    const wantHtml = args.fetchHTMLBodyValues === true || args.fetchAllBodyValues === true;
+    if (wantText || (wantHtml && !email.bodyHtmlR2Key)) bodyValues.text = bodyValue(email.bodyText ?? "");
+    if (wantHtml && email.bodyHtmlR2Key) {
+      const object = await env.MAIL_STORAGE.get(email.bodyHtmlR2Key);
+      bodyValues.html = bodyValue(object ? await object.text() : "");
+    }
+  }
+  const timestamp = email.timelineAt.toISOString();
+  const object = {
+    id: email.id,
+    blobId: raw,
+    threadId: email.conversationId,
+    mailboxIds: { [row.mailboxId]: true },
+    keywords: row.seen ? { $seen: true } : {},
+    size: (email.bodyText?.length ?? 0) + email.attachmentsJson.reduce((total, attachment) => total + attachment.size, 0),
+    receivedAt: timestamp,
+    messageId: email.messageIdHeader ? [email.messageIdHeader.replace(/^<|>$/gu, "")] : null,
+    inReplyTo: email.inReplyToJson?.length ? email.inReplyToJson : null,
+    references: email.referencesJson?.length ? email.referencesJson : null,
+    sender: null,
+    from: addresses(email.fromJson),
+    to: addresses(email.toJson),
+    cc: addresses(email.ccJson),
+    bcc: addresses(email.bccJson),
+    replyTo: addresses(email.replyToJson),
+    subject: email.subject,
+    sentAt: timestamp,
+    hasAttachment: attachments.some((attachment) => attachment.disposition === "attachment"),
+    preview: email.preview,
+    bodyValues,
+    textBody,
+    htmlBody,
+    attachments,
+    bodyStructure: { partId: null, type: "multipart/mixed", subParts: [...htmlBody, ...attachments] },
+  };
+  return Object.fromEntries(Object.entries(object).filter(([key]) => key === "id" || properties.includes(key)));
+}
+
+async function emailGet(state: RequestState, args: Args) {
+  const owner = account(state, args);
+  if (args.ids == null) throw new MethodError("requestTooLarge", "Ask for emails by id");
+  const ids = stringIds(args.ids);
+  const result = await mailboxStub(state.context.env, owner.id).jmapEmails(state.context.user.id, ids);
+  const found = new Set(result.emails.map((row) => row.email.id));
+  return {
+    accountId: owner.id,
+    state: result.state,
+    list: await Promise.all(result.emails.map((row) => emailObject(state.context.env, row as never, args))),
+    notFound: ids.filter((id) => !found.has(id)),
+  };
+}
+
+/** The keyword and mailbox changes in an Email/set update patch. */
+function emailPatch(patch: Args) {
+  let seen: boolean | undefined;
+  let target: string | undefined;
+  for (const [key, value] of Object.entries(patch)) {
+    if (key === "keywords" && isRecord(value)) {
+      const keywords = Object.keys(value);
+      if (keywords.some((keyword) => keyword !== "$seen")) return { error: "Only the $seen keyword is stored" };
+      seen = value.$seen === true;
+    } else if (key === "keywords/$seen") {
+      seen = value === true;
+    } else if (key.startsWith("keywords/")) {
+      return { error: "Only the $seen keyword is stored" };
+    } else if (key === "mailboxIds" && isRecord(value)) {
+      const ids = Object.keys(value).filter((id) => value[id] === true);
+      if (ids.length !== 1) return { error: "An email is in exactly one mailbox" };
+      target = ids[0];
+    } else if (key.startsWith("mailboxIds/")) {
+      if (value === true) target = key.slice("mailboxIds/".length);
+    } else {
+      return { error: `${key} cannot be changed` };
+    }
+  }
+  return { seen, target };
+}
+
+function draftFrom(owner: JmapAccount, input: Args): Draft | string {
+  const list = (value: unknown) =>
+    Array.isArray(value) ? value.flatMap((item) => isRecord(item) && typeof item.email === "string" ? [item.email] : []) : [];
+  const bodyValues = isRecord(input.bodyValues) ? input.bodyValues : {};
+  const partText = (parts: unknown) => {
+    if (!Array.isArray(parts) || !isRecord(parts[0])) return undefined;
+    const value = bodyValues[String(parts[0].partId)];
+    return isRecord(value) && typeof value.value === "string" ? value.value : undefined;
+  };
+  const bodyText = partText(input.textBody);
+  const bodyHtml = partText(input.htmlBody);
+  if (bodyText === undefined && bodyHtml === undefined) return "Give the message a textBody or htmlBody with bodyValues";
+  return {
+    accountId: owner.id,
+    to: list(input.to),
+    cc: list(input.cc),
+    bcc: list(input.bcc),
+    subject: typeof input.subject === "string" ? input.subject : "",
+    bodyText: bodyText ?? "",
+    ...(bodyHtml !== undefined ? { bodyHtml } : {}),
+  };
+}
+
+async function emailSet(state: RequestState, args: Args) {
+  const owner = account(state, args);
+  const stub = mailboxStub(state.context.env, owner.id);
+  const oldState = await stub.jmapState();
+  if (args.ifInState !== undefined && args.ifInState !== oldState) throw new MethodError("stateMismatch");
+  const created: Args = {};
+  const notCreated: Args = {};
+  for (const [creationId, input] of Object.entries(isRecord(args.create) ? args.create : {})) {
+    const draft = isRecord(input) ? draftFrom(owner, input) : "Invalid email";
+    if (typeof draft === "string") {
+      notCreated[creationId] = { type: "invalidProperties", description: draft };
+      continue;
+    }
+    // Drafts are not stored: one is sent by EmailSubmission/set in the same request.
+    const id = `draft-${crypto.randomUUID()}`;
+    state.drafts.set(id, draft);
+    state.createdIds[creationId] = id;
+    created[creationId] = { id, blobId: `draft~${id}`, threadId: id, size: draft.bodyText.length };
+  }
+
+  const updated: Args = {};
+  const notUpdated: Args = {};
+  const reads: Array<[string, boolean]> = [];
+  const moves = new Map<string, string[]>();
+  for (const [id, patch] of Object.entries(isRecord(args.update) ? args.update : {})) {
+    const change = isRecord(patch) ? emailPatch(patch) : { error: "Invalid patch" };
+    if ("error" in change && change.error) {
+      notUpdated[id] = { type: "invalidProperties", description: change.error };
+      continue;
+    }
+    const { seen, target } = change as { seen?: boolean; target?: string };
+    if (seen !== undefined) reads.push([id, seen]);
+    if (target) moves.set(target, [...(moves.get(target) ?? []), id]);
+    updated[id] = null;
+  }
+  for (const [id, seen] of reads) {
+    if (!(await stub.setMessageRead(state.context.user.id, id, seen))) {
+      delete updated[id];
+      notUpdated[id] = { type: "notFound" };
+    }
+  }
+  for (const [target, ids] of moves) {
+    if (!(await stub.jmapMoveEmails(ids, target))) {
+      for (const id of ids) {
+        delete updated[id];
+        notUpdated[id] = { type: "invalidProperties", description: `Emails cannot be moved to ${target}` };
+      }
+    }
+  }
+
+  const destroyed: string[] = [];
+  const notDestroyed: Args = {};
+  const destroyIds = args.destroy == null ? [] : stringIds(args.destroy, "destroy");
+  if (destroyIds.length) {
+    const { emails } = await stub.jmapEmails(state.context.user.id, destroyIds);
+    const inTrash = emails.filter((row) => row.mailboxId === "trash");
+    const elsewhere = emails.filter((row) => row.mailboxId !== "trash");
+    // Mail goes to Trash first; destroying it there deletes its conversation.
+    if (elsewhere.length) await stub.jmapMoveEmails(elsewhere.map((row) => row.email.id), "trash");
+    if (inTrash.length) {
+      await stub.permanentlyDeleteConversations([...new Set(inTrash.map((row) => row.email.conversationId))]);
+    }
+    const found = new Set(emails.map((row) => row.email.id));
+    for (const id of destroyIds) {
+      if (found.has(id)) destroyed.push(id);
+      else notDestroyed[id] = { type: "notFound" };
+    }
+  }
+  return {
+    accountId: owner.id,
+    oldState,
+    newState: await stub.jmapState(),
+    created: Object.keys(created).length ? created : null,
+    updated: Object.keys(updated).length ? updated : null,
+    destroyed: destroyed.length ? destroyed : null,
+    notCreated: Object.keys(notCreated).length ? notCreated : null,
+    notUpdated: Object.keys(notUpdated).length ? notUpdated : null,
+    notDestroyed: Object.keys(notDestroyed).length ? notDestroyed : null,
+  };
+}
+
+// --------------------------------------------------- threads and identities
+
+async function threadGet(state: RequestState, args: Args) {
+  const owner = account(state, args);
+  const ids = stringIds(args.ids);
+  const result = await mailboxStub(state.context.env, owner.id).jmapThreads(ids);
+  const threads = new Map(result.threads as Array<[string, string[]]>);
+  return {
+    accountId: owner.id,
+    state: result.state,
+    list: ids.flatMap((id) => threads.has(id) ? [{ id, emailIds: threads.get(id)! }] : []),
+    notFound: ids.filter((id) => !threads.has(id)),
+  };
+}
+
+function identityGet(state: RequestState, args: Args) {
+  const owner = account(state, args);
+  const list = owner.canSend
+    ? [{
+      id: owner.id,
+      name: owner.displayName,
+      email: owner.address,
+      replyTo: null,
+      bcc: null,
+      textSignature: "",
+      htmlSignature: "",
+      mayDelete: false,
+    }]
+    : [];
+  const ids = args.ids == null ? list.map((identity) => identity.id) : stringIds(args.ids);
+  return {
+    accountId: owner.id,
+    state: "1",
+    list: list.filter((identity) => ids.includes(identity.id)),
+    notFound: ids.filter((id) => id !== owner.id || !owner.canSend),
+  };
+}
+
+async function submissionSet(state: RequestState, args: Args, callId: string) {
+  const owner = account(state, args);
+  if (!owner.canSend) throw new MethodError("forbidden", "This account cannot send");
+  const created: Args = {};
+  const notCreated: Args = {};
+  const sentDrafts = new Map<string, string>();
+  for (const [creationId, input] of Object.entries(isRecord(args.create) ? args.create : {})) {
+    if (!isRecord(input) || typeof input.emailId !== "string") {
+      notCreated[creationId] = { type: "invalidProperties", description: "emailId is required" };
+      continue;
+    }
+    const emailId = input.emailId.startsWith("#")
+      ? state.createdIds[input.emailId.slice(1)]
+      : input.emailId;
+    const draft = emailId ? state.drafts.get(emailId) : undefined;
+    if (!draft || draft.accountId !== owner.id) {
+      notCreated[creationId] = {
+        type: "invalidProperties",
+        description: "Send an email created by Email/set earlier in the same request",
+      };
+      continue;
+    }
+    if (input.identityId !== undefined && input.identityId !== owner.id) {
+      notCreated[creationId] = { type: "invalidProperties", description: "Unknown identity" };
+      continue;
+    }
+    try {
+      const submission = await submitOutgoing({
+        env: state.context.env,
+        requestUrl: state.context.requestUrl,
+        compose: {
+          requestId: crypto.randomUUID(),
+          mailboxId: owner.id,
+          to: draft.to,
+          cc: draft.cc,
+          bcc: draft.bcc,
+          subject: draft.subject,
+          bodyText: draft.bodyText,
+          ...(draft.bodyHtml !== undefined ? { bodyHtml: draft.bodyHtml } : {}),
+          attachments: [],
+          userId: state.context.user.id,
+        },
+        conversationId: `conv_${crypto.randomUUID().replaceAll("-", "")}`,
+        related: null,
+        forwarded: null,
+        includeRelatedContext: false,
+        fromAddress: owner.address,
+        fromName: owner.displayName,
+        defer: state.context.defer,
+      });
+      const id = `sub-${submission.email.id}`;
+      state.createdIds[creationId] = id;
+      sentDrafts.set(id, emailId!);
+      created[creationId] = {
+        id,
+        threadId: submission.email.conversationId,
+        emailId: submission.email.id,
+        sendAt: new Date().toISOString(),
+        undoStatus: "final",
+      };
+    } catch (error) {
+      notCreated[creationId] = {
+        type: "forbiddenToSend",
+        description: error instanceof Error ? error.message : "The message could not be sent",
+      };
+    }
+  }
+  // The sent copy is already in Sent; drafts were never stored, so the
+  // follow-up Email/set only reports them gone.
+  const followUp = [args.onSuccessDestroyEmail, args.onSuccessUpdateEmail ? Object.keys(args.onSuccessUpdateEmail as Args) : null]
+    .flatMap((value) => Array.isArray(value) ? value as string[] : [])
+    .map((reference) => reference.startsWith("#") ? state.createdIds[reference.slice(1)] : reference)
+    .flatMap((id) => id && sentDrafts.has(id) ? [sentDrafts.get(id)!] : []);
+  if (followUp.length) {
+    const stub = mailboxStub(state.context.env, owner.id);
+    const current = await stub.jmapState();
+    state.after.push(["Email/set", {
+      accountId: owner.id, oldState: current, newState: current,
+      created: null, updated: null, destroyed: followUp,
+      notCreated: null, notUpdated: null, notDestroyed: null,
+    }, callId]);
+  }
+  return {
+    accountId: owner.id,
+    oldState: "1",
+    newState: "1",
+    created: Object.keys(created).length ? created : null,
+    notCreated: Object.keys(notCreated).length ? notCreated : null,
+    updated: null,
+    destroyed: null,
+    notUpdated: null,
+    notDestroyed: null,
+  };
+}
+
+// ----------------------------------------------------------------- dispatch
+
+const methods: Record<string, (state: RequestState, args: Args, callId: string) => unknown> = {
+  "Core/echo": (_state, args) => args,
+  "Mailbox/get": mailboxGet,
+  "Mailbox/query": mailboxQuery,
+  "Mailbox/changes": async (state, args) => {
+    const owner = account(state, args);
+    return changes(owner.id, args.sinceState, await mailboxStub(state.context.env, owner.id).jmapState());
+  },
+  "Email/query": emailQuery,
+  "Email/get": emailGet,
+  "Email/set": emailSet,
+  "Email/changes": async (state, args) => {
+    const owner = account(state, args);
+    return changes(owner.id, args.sinceState, await mailboxStub(state.context.env, owner.id).jmapState());
+  },
+  "Thread/get": threadGet,
+  "Thread/changes": async (state, args) => {
+    const owner = account(state, args);
+    return changes(owner.id, args.sinceState, await mailboxStub(state.context.env, owner.id).jmapState());
+  },
+  "SearchSnippet/get": (state, args) => {
+    const owner = account(state, args);
+    const ids = stringIds(args.emailIds, "emailIds");
+    return { accountId: owner.id, list: ids.map((emailId) => ({ emailId, subject: null, preview: null })), notFound: [] };
+  },
+  "Identity/get": identityGet,
+  "EmailSubmission/set": submissionSet,
+};
+
+export async function runJmapRequest(context: JmapContext, body: unknown) {
+  if (!isRecord(body) || !Array.isArray(body.using) || !Array.isArray(body.methodCalls)) {
+    throw new JmapError("urn:ietf:params:jmap:error:notRequest", "A JMAP request has using and methodCalls");
+  }
+  if (!body.using.includes(CORE)) {
+    throw new JmapError("urn:ietf:params:jmap:error:unknownCapability", `${CORE} is required`);
+  }
+  if (body.methodCalls.length > 32) {
+    throw new JmapError("urn:ietf:params:jmap:error:limit", "At most 32 method calls per request");
+  }
+  const state: RequestState = {
+    context,
+    responses: [],
+    createdIds: isRecord(body.createdIds) ? { ...body.createdIds as Record<string, string> } : {},
+    drafts: new Map(),
+    after: [],
+  };
+  for (const call of body.methodCalls) {
+    if (!Array.isArray(call) || typeof call[0] !== "string" || !isRecord(call[1]) || typeof call[2] !== "string") {
+      throw new JmapError("urn:ietf:params:jmap:error:notRequest", "Each method call is [name, arguments, id]");
+    }
+    const [name, rawArgs, callId] = call as Invocation;
+    const method = methods[name];
+    try {
+      if (!method) throw new MethodError("unknownMethod");
+      const args = resolveReferences(state, rawArgs);
+      state.responses.push([name, await method(state, args, callId) as Args, callId]);
+      state.responses.push(...state.after.splice(0));
+    } catch (error) {
+      if (!(error instanceof MethodError)) throw error;
+      state.responses.push(["error", { type: error.type, description: error.message }, callId]);
+    }
+  }
+  return {
+    methodResponses: state.responses,
+    ...(isRecord(body.createdIds) ? { createdIds: state.createdIds } : {}),
+    sessionState: String(context.accounts.length),
+  };
+}

package/worker/jmap/routes.ts

@@ -0,0 +1,176 @@
+import { and, eq } from "drizzle-orm";
+import { Hono, type Context } from "hono";
+import { JMAP_SCOPE } from "@open-workspace/core/shared/oidc.ts";
+import { bearerToken } from "@open-workspace/core/worker/auth/middleware.ts";
+import { createDb } from "@open-workspace/core/worker/db/client.ts";
+import { mailboxAddressSql } from "@open-workspace/core/worker/db/mailboxes.ts";
+import { domains, mailboxAccess, mailboxes } from "@open-workspace/core/worker/db/schema.ts";
+import type { AppEnv } from "@open-workspace/core/worker/env.ts";
+import {
+  authenticateAccessToken,
+  jmapProtectedResourceMetadataUrl,
+} from "@open-workspace/core/worker/oidc/mcp-clients.ts";
+import { mailboxStub } from "../mailbox";
+import { JmapError, runJmapRequest, type JmapAccount, type JmapContext } from "./methods";
+
+const CAPABILITIES = {
+  "urn:ietf:params:jmap:core": {
+    maxSizeUpload: 0,
+    maxConcurrentUpload: 1,
+    maxSizeRequest: 10_000_000,
+    maxConcurrentRequests: 4,
+    maxCallsInRequest: 32,
+    maxObjectsInGet: 500,
+    maxObjectsInSet: 500,
+    collationAlgorithms: ["i;unicode-casemap"],
+  },
+  "urn:ietf:params:jmap:mail": {},
+  "urn:ietf:params:jmap:submission": {},
+};
+
+type JmapEnv = AppEnv & { Variables: AppEnv["Variables"] & { jmapUser: { id: string; name: string } } };
+
+function problem(c: Context, status: 400 | 401 | 403 | 404 | 501, type: string, detail: string) {
+  return c.json({ type, status, detail }, status, { "content-type": "application/problem+json" });
+}
+
+/** The mailboxes this person can open; each is a JMAP account. */
+async function jmapAccounts(env: Env, userId: string): Promise<JmapAccount[]> {
+  const rows = await createDb(env.DB)
+    .select({
+      id: mailboxes.id,
+      address: mailboxAddressSql,
+      displayName: mailboxes.displayName,
+      ownerUserId: mailboxes.ownerUserId,
+      isPrimary: mailboxes.isPrimary,
+      canSend: mailboxAccess.canSend,
+    })
+    .from(mailboxAccess)
+    .innerJoin(mailboxes, eq(mailboxAccess.mailboxId, mailboxes.id))
+    .innerJoin(domains, eq(mailboxes.domainId, domains.id))
+    .where(and(eq(mailboxAccess.userId, userId), eq(mailboxes.delivery, "inbox")));
+  return rows.map((row) => ({
+    ...row,
+    isPersonal: row.ownerUserId === userId,
+  }));
+}
+
+function sessionObject(origin: string, user: { id: string; name: string }, accounts: JmapAccount[]) {
+  const primary = accounts.find((account) => account.isPersonal && account.isPrimary)
+    ?? accounts.find((account) => account.isPersonal)
+    ?? accounts[0];
+  return {
+    capabilities: CAPABILITIES,
+    accounts: Object.fromEntries(accounts.map((account) => [account.id, {
+      name: account.address,
+      isPersonal: account.isPersonal,
+      isReadOnly: false,
+      accountCapabilities: {
+        "urn:ietf:params:jmap:mail": {
+          maxMailboxesPerEmail: 1,
+          maxMailboxDepth: 1,
+          maxSizeMailboxName: 80,
+          maxSizeAttachmentsPerEmail: 0,
+          emailQuerySortOptions: ["receivedAt", "sentAt"],
+          mayCreateTopLevelMailbox: false,
+        },
+        ...(account.canSend
+          ? { "urn:ietf:params:jmap:submission": { maxDelayedSend: 0, submissionExtensions: {} } }
+          : {}),
+      },
+    }])),
+    primaryAccounts: primary
+      ? {
+        "urn:ietf:params:jmap:mail": primary.id,
+        "urn:ietf:params:jmap:submission": primary.id,
+      }
+      : {},
+    username: primary?.address ?? user.name,
+    apiUrl: `${origin}/jmap/api`,
+    downloadUrl: `${origin}/jmap/download/{accountId}/{blobId}/{name}?type={type}`,
+    uploadUrl: `${origin}/jmap/upload/{accountId}`,
+    eventSourceUrl: `${origin}/jmap/eventsource?types={types}&closeafter={closeafter}&ping={ping}`,
+    state: String(accounts.length),
+  };
+}
+
+const requireJmapAuth = async (c: Context<JmapEnv>, next: () => Promise<void>) => {
+  const token = bearerToken(c.req.raw);
+  const identity = token
+    ? await authenticateAccessToken(createDb(c.env.DB), token, JMAP_SCOPE)
+    : null;
+  if (!identity) {
+    c.header("www-authenticate", [
+      `Bearer resource_metadata="${jmapProtectedResourceMetadataUrl(new URL(c.req.url).origin)}"`,
+      `scope="${JMAP_SCOPE}"`,
+      ...(token ? ['error="invalid_token"'] : []),
+    ].join(", "));
+    return problem(c, 401, "about:blank", token ? "The access token is invalid or expired" : "Sign in with OAuth");
+  }
+  c.set("jmapUser", { id: identity.user.id, name: identity.user.name });
+  await next();
+};
+
+/**
+ * JMAP (RFC 8620) for mail (RFC 8621) with OAuth bearer tokens carrying the
+ * jmap scope. Each mailbox the person can open is a JMAP account.
+ */
+export const jmapRoutes = new Hono<JmapEnv>()
+  .get("/.well-known/jmap", (c) => c.redirect("/jmap/session", 302))
+  .use("/jmap/*", requireJmapAuth)
+  .get("/jmap/session", async (c) => {
+    const user = c.get("jmapUser");
+    return c.json(sessionObject(new URL(c.req.url).origin, user, await jmapAccounts(c.env, user.id)));
+  })
+  .post("/jmap/api", async (c) => {
+    if (!c.req.header("content-type")?.toLowerCase().startsWith("application/json")) {
+      return problem(c, 400, "urn:ietf:params:jmap:error:notJSON", "The request must be JSON");
+    }
+    let body: unknown;
+    try {
+      body = await c.req.json();
+    } catch {
+      return problem(c, 400, "urn:ietf:params:jmap:error:notJSON", "The request is not valid JSON");
+    }
+    const user = c.get("jmapUser");
+    const context: JmapContext = {
+      env: c.env,
+      user,
+      accounts: await jmapAccounts(c.env, user.id),
+      requestUrl: c.req.url,
+      defer: (task) => c.executionCtx.waitUntil(task),
+    };
+    try {
+      return c.json(await runJmapRequest(context, body));
+    } catch (error) {
+      if (error instanceof JmapError) return problem(c, 400, error.type, error.message);
+      throw error;
+    }
+  })
+  .get("/jmap/download/:accountId/:blobId/:name", async (c) => {
+    const user = c.get("jmapUser");
+    const account = (await jmapAccounts(c.env, user.id)).find((item) => item.id === c.req.param("accountId"));
+    if (!account) return problem(c, 404, "about:blank", "Account not found");
+    const blob = /^(raw|att)~([^~]+)(?:~(.+))?$/u.exec(c.req.param("blobId"));
+    if (!blob) return problem(c, 404, "about:blank", "Blob not found");
+    const [, kind, emailId, attachmentId] = blob;
+    const stub = mailboxStub(c.env, account.id);
+    const email = await stub.getEmail(emailId!);
+    const key = kind === "raw"
+      ? email?.rawMimeR2Key
+      : email?.attachmentsJson.find((attachment) => attachment.id === attachmentId)?.r2Key;
+    const object = key ? await c.env.MAIL_STORAGE.get(key) : null;
+    if (!object) return problem(c, 404, "about:blank", "Blob not found");
+    const type = c.req.query("type") || (kind === "raw" ? "message/rfc822" : "application/octet-stream");
+    return new Response(object.body, {
+      headers: {
+        "content-type": type,
+        "content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(c.req.param("name"))}`,
+        "cache-control": "private, immutable, max-age=31536000",
+      },
+    });
+  })
+  .post("/jmap/upload/:accountId", (c) =>
+    problem(c, 501, "about:blank", "Uploads are not supported yet; send attachments from the app"))
+  .get("/jmap/eventsource", (c) =>
+    problem(c, 501, "about:blank", "Push over EventSource is not supported yet"));

package/worker/mailbox/index.ts

@@ -4,6 +4,15 @@ import { drizzle, type DrizzleSqliteDODatabase } from "drizzle-orm/durable-sqlit
 import { migrate } from "drizzle-orm/durable-sqlite/migrator";
 import migrations from "./migrations";
 import { upgradeLegacyMailbox } from "./legacy-migrations";
+import {
+  bumpJmapState,
+  emailPlacement as jmapEmailPlacement,
+  jmapState,
+  mailboxes as jmapMailboxRows,
+  moveEmails as jmapMoveEmails,
+  queryEmails as queryJmapEmails,
+  threadEmails as jmapThreadEmails,
+} from "./jmap-store";
 import { officePreviewExtension, officePreviewKey } from "../../shared/office-preview";
 import {
   dispatchOfficePreviewJobs,
@@ -497,6 +506,7 @@ export class MailboxDO extends DurableObject<Env> {
   }
 
   private publishUpdate() {
+    bumpJmapState(this.state.storage);
     this.state.waitUntil(this.broadcastUpdate().catch((error) => {
       console.error("Could not authorize realtime delivery", error);
     }));
@@ -852,6 +862,41 @@ export class MailboxDO extends DurableObject<Env> {
     return this.getMailboxAiSettings();
   }
 
+  jmapState() {
+    return jmapState(this.state.storage);
+  }
+
+  jmapMailboxes(userId: string) {
+    return { state: jmapState(this.state.storage), mailboxes: jmapMailboxRows(this.state.storage.sql, userId) };
+  }
+
+  jmapQueryEmails(input: Parameters<typeof queryJmapEmails>[1]) {
+    return { state: jmapState(this.state.storage), ...queryJmapEmails(this.state.storage.sql, input) };
+  }
+
+  /** Emails with their JMAP Mailbox and this user's $seen keyword; unknown ids are left out. */
+  jmapEmails(userId: string, ids: string[]) {
+    const placement = jmapEmailPlacement(this.state.storage.sql, userId, ids);
+    return {
+      state: jmapState(this.state.storage),
+      emails: ids.flatMap((id) => {
+        const email = this.getEmail(id);
+        const place = placement.get(id);
+        return email && place ? [{ email, ...place }] : [];
+      }),
+    };
+  }
+
+  jmapThreads(ids: string[]) {
+    return { state: jmapState(this.state.storage), threads: [...jmapThreadEmails(this.state.storage.sql, ids)] };
+  }
+
+  jmapMoveEmails(emailIds: string[], target: string) {
+    const moved = jmapMoveEmails(this.state.storage.sql, emailIds, target);
+    if (moved) this.publishUpdate();
+    return moved;
+  }
+
   getEmail(id: string) {
     return this.db.select().from(emails).where(eq(emails.id, id)).all()[0] ?? null;
   }

package/worker/mailbox/jmap-store.ts

@@ -0,0 +1,238 @@
+/**
+ * JMAP views over a mailbox's SQLite store (RFC 8621). A JMAP Mailbox is a
+ * system folder or a custom folder; an email sits in exactly one, derived
+ * from its conversation's state and its own direction.
+ */
+
+/** Which JMAP Mailbox an email (alias e) of conversation (alias c) is in. */
+export const EMAIL_MAILBOX_SQL = `case
+  when c.mailbox_state = 'trash' then 'trash'
+  when c.mailbox_state = 'spam' then 'spam'
+  when c.mailbox_state = 'archive' then 'archive'
+  when e.direction = 'outgoing' then 'sent'
+  when c.folder_id is not null then c.folder_id
+  else 'inbox'
+end`;
+
+const SYSTEM_MAILBOXES = [
+  { id: "inbox", name: "Inbox", role: "inbox", sortOrder: 0 },
+  { id: "sent", name: "Sent", role: "sent", sortOrder: 1_000 },
+  { id: "archive", name: "Archive", role: "archive", sortOrder: 1_010 },
+  { id: "spam", name: "Spam", role: "junk", sortOrder: 1_020 },
+  { id: "trash", name: "Trash", role: "trash", sortOrder: 1_030 },
+] as const;
+
+export type JmapMailboxRow = {
+  id: string;
+  name: string;
+  role: string | null;
+  sortOrder: number;
+  totalEmails: number;
+  unreadEmails: number;
+  totalThreads: number;
+  unreadThreads: number;
+};
+
+export type JmapEmailFilter = {
+  inMailbox?: string;
+  inMailboxOtherThan?: string[];
+  before?: number;
+  after?: number;
+  text?: string;
+  from?: string;
+  to?: string;
+  subject?: string;
+  hasKeyword?: string;
+  notKeyword?: string;
+  hasAttachment?: boolean;
+};
+
+const STATE_KEY = "jmap:state";
+
+/** A counter bumped on every change; JMAP clients compare it to resync. */
+export function jmapState(storage: DurableObjectStorage) {
+  return String(storage.kv.get<number>(STATE_KEY) ?? 0);
+}
+
+export function bumpJmapState(storage: DurableObjectStorage) {
+  storage.kv.put(STATE_KEY, (storage.kv.get<number>(STATE_KEY) ?? 0) + 1);
+}
+
+const unread = (userId: string) => ({
+  sql: "not exists (select 1 from email_read_states r where r.email_id = e.id and r.user_id = ?)",
+  params: [userId],
+});
+
+export function mailboxes(sql: SqlStorage, userId: string): JmapMailboxRow[] {
+  const isUnread = unread(userId);
+  const counts = new Map(
+    sql.exec<{ mailbox: string; total: number; unread: number; threads: number; unread_threads: number }>(`
+      select mailbox,
+        count(*) as total,
+        sum(is_unread) as unread,
+        count(distinct conversation_id) as threads,
+        count(distinct case when is_unread then conversation_id end) as unread_threads
+      from (
+        select ${EMAIL_MAILBOX_SQL} as mailbox, e.conversation_id, ${isUnread.sql} as is_unread
+        from emails e join conversations c on c.id = e.conversation_id
+      )
+      group by mailbox`, ...isUnread.params).toArray().map((row) => [row.mailbox, row]),
+  );
+  const custom = sql.exec<{ id: string; name: string; sort_order: number }>(
+    "select id, name, sort_order from folders order by sort_order, name",
+  ).toArray();
+  const rows = [
+    ...SYSTEM_MAILBOXES.map((mailbox) => ({ ...mailbox })),
+    ...custom.map((folder) => ({ id: folder.id, name: folder.name, role: null, sortOrder: 10 + folder.sort_order })),
+  ];
+  return rows.map((mailbox) => {
+    const count = counts.get(mailbox.id);
+    return {
+      ...mailbox,
+      totalEmails: count?.total ?? 0,
+      unreadEmails: count?.unread ?? 0,
+      totalThreads: count?.threads ?? 0,
+      unreadThreads: count?.unread_threads ?? 0,
+    };
+  });
+}
+
+function ftsQuery(text: string) {
+  // Each word must appear; quoting keeps FTS syntax out of user input.
+  return text
+    .split(/\s+/u)
+    .filter(Boolean)
+    .map((word) => `"${word.replaceAll('"', '""')}"`)
+    .join(" ");
+}
+
+export function queryEmails(
+  sql: SqlStorage,
+  input: {
+    userId: string;
+    filter: JmapEmailFilter;
+    ascending: boolean;
+    position: number;
+    limit: number;
+    collapseThreads: boolean;
+  },
+) {
+  const where: string[] = [];
+  const params: unknown[] = [];
+  const { filter } = input;
+  if (filter.inMailbox) {
+    where.push(`${EMAIL_MAILBOX_SQL} = ?`);
+    params.push(filter.inMailbox);
+  }
+  if (filter.inMailboxOtherThan?.length) {
+    where.push(`${EMAIL_MAILBOX_SQL} not in (${filter.inMailboxOtherThan.map(() => "?").join(", ")})`);
+    params.push(...filter.inMailboxOtherThan);
+  }
+  if (filter.before !== undefined) {
+    where.push("e.timeline_at < ?");
+    params.push(filter.before);
+  }
+  if (filter.after !== undefined) {
+    where.push("e.timeline_at >= ?");
+    params.push(filter.after);
+  }
+  if (filter.text?.trim()) {
+    where.push("e.id in (select email_id from email_search where email_search match ?)");
+    params.push(ftsQuery(filter.text));
+  }
+  for (const [field, column] of [["from", "e.from_json"], ["subject", "e.subject"]] as const) {
+    const value = filter[field];
+    if (value) {
+      where.push(`lower(${column}) like ?`);
+      params.push(`%${value.toLowerCase()}%`);
+    }
+  }
+  if (filter.to) {
+    where.push("(lower(e.to_json) like ? or lower(e.cc_json) like ?)");
+    params.push(`%${filter.to.toLowerCase()}%`, `%${filter.to.toLowerCase()}%`);
+  }
+  const isUnread = unread(input.userId);
+  if (filter.hasKeyword === "$seen") {
+    where.push(`not ${isUnread.sql}`);
+    params.push(...isUnread.params);
+  }
+  if (filter.notKeyword === "$seen") {
+    where.push(isUnread.sql);
+    params.push(...isUnread.params);
+  }
+  if (filter.hasAttachment !== undefined) {
+    where.push(filter.hasAttachment
+      ? "json_array_length(e.attachments_json) > 0"
+      : "json_array_length(e.attachments_json) = 0");
+  }
+  const direction = input.ascending ? "asc" : "desc";
+  const filtered = `
+    select e.id, e.conversation_id, e.timeline_at,
+      row_number() over (partition by e.conversation_id order by e.timeline_at desc, e.id desc) as thread_rank
+    from emails e join conversations c on c.id = e.conversation_id
+    ${where.length ? `where ${where.join(" and ")}` : ""}`;
+  const rows = sql.exec<{ id: string; total: number }>(`
+    select id, count(*) over () as total from (${filtered})
+    ${input.collapseThreads ? "where thread_rank = 1" : ""}
+    order by timeline_at ${direction}, id ${direction}
+    limit ? offset ?`, ...params, input.limit, input.position).toArray();
+  const total = rows[0]?.total ?? sql.exec<{ total: number }>(
+    `select count(*) as total from (${filtered}) ${input.collapseThreads ? "where thread_rank = 1" : ""}`,
+    ...params,
+  ).one().total;
+  return { ids: rows.map((row) => row.id), total };
+}
+
+/** For each email: its JMAP Mailbox, and whether this user has read it. */
+export function emailPlacement(sql: SqlStorage, userId: string, ids: string[]) {
+  if (!ids.length) return new Map<string, { mailboxId: string; seen: boolean }>();
+  const isUnread = unread(userId);
+  return new Map(
+    sql.exec<{ id: string; mailbox: string; is_unread: number }>(`
+      select e.id, ${EMAIL_MAILBOX_SQL} as mailbox, ${isUnread.sql} as is_unread
+      from emails e join conversations c on c.id = e.conversation_id
+      where e.id in (${ids.map(() => "?").join(", ")})`, ...isUnread.params, ...ids)
+      .toArray()
+      .map((row) => [row.id, { mailboxId: row.mailbox, seen: !row.is_unread }]),
+  );
+}
+
+export function threadEmails(sql: SqlStorage, threadIds: string[]) {
+  const threads = new Map<string, string[]>();
+  if (!threadIds.length) return threads;
+  for (const row of sql.exec<{ id: string; conversation_id: string }>(
+    `select id, conversation_id from emails where conversation_id in (${threadIds.map(() => "?").join(", ")})
+     order by timeline_at, id`,
+    ...threadIds,
+  )) {
+    threads.set(row.conversation_id, [...(threads.get(row.conversation_id) ?? []), row.id]);
+  }
+  return threads;
+}
+
+/**
+ * Moves the conversations of `emailIds` into a JMAP Mailbox. Conversations
+ * move as a whole, as they do in the app. Returns false for an unknown or
+ * read-only target.
+ */
+export function moveEmails(sql: SqlStorage, emailIds: string[], target: string) {
+  if (!emailIds.length) return true;
+  let state: string;
+  let folderId: string | null = null;
+  if (target === "inbox") state = "active";
+  else if (target === "archive" || target === "spam" || target === "trash") state = target;
+  else if (sql.exec("select 1 from folders where id = ?", target).toArray().length) {
+    state = "active";
+    folderId = target;
+  } else {
+    return false;
+  }
+  sql.exec(
+    `update conversations set mailbox_state = ?, folder_id = ?
+     where id in (select conversation_id from emails where id in (${emailIds.map(() => "?").join(", ")}))`,
+    state,
+    folderId,
+    ...emailIds,
+  );
+  return true;
+}

package/worker/module.ts

@@ -16,6 +16,7 @@ import { mailRoutes } from "./mail/routes";
 import { emailWebhookData } from "./mail/webhook-source";
 import { seedEmailDemo } from "./mailbox/demo-seed";
 import { registerMailTools } from "./mcp/tools";
+import { jmapRoutes } from "./jmap/routes";
 
 /** Routes the browser and MCP use under /api. */
 export const mailAccountApi = new Hono<AppEnv>()
@@ -23,6 +24,7 @@ export const mailAccountApi = new Hono<AppEnv>()
   .route("/admin", reportAdminRoutes);
 
 const mailPublicRoutes = new Hono<AppEnv>()
+  .route("/", jmapRoutes as unknown as Hono<AppEnv>)
   .route("/api/downloads", mailDownloadRoutes)
   .route("/api/demo", demoRoutes)
   .route("/api/notifications", pushNotificationRoutes);