@k2b/cloud 0.27.0 → 0.28.0

package/src/api/admin-outgoing-mail.ts

@@ -1,19 +1,40 @@
+import { sql } from "bun";
 import { type Context, Hono, type MiddlewareHandler } from "hono";
-import { validator } from "hono-openapi";
+import { describeRoute, validator } from "hono-openapi";
 import { z } from "zod";
-import { MailAppAccessSchema, MailProfileInputSchema, MailProfileKeySchema } from "../contracts/outgoing-mail";
-import { type AuthContext, auth } from "../server";
+import {
+  AdminMailRecordSchema,
+  MailAppAccessSchema,
+  MailProfileInputSchema,
+  MailProfileKeySchema,
+  MailRetentionSchema,
+  MailStatusSchema,
+} from "../contracts/outgoing-mail";
+import { type AuthContext, auth, jsonResponse, requiresAdmin } from "../server";
+import { audit } from "../services/audit";
+import { outgoingMailLog } from "../services/outgoing-mail/admin";
+import { MAIL_RETENTION_KEYS, readMailRetention } from "../services/outgoing-mail/retention";
 import { type MailAuditContext, OutgoingMailError, outgoingMailStore } from "../services/outgoing-mail/store";
 import { outgoingMailTest } from "../services/outgoing-mail/test-send";
+import * as settings from "../services/settings";
 
-const validate = <Target extends "param" | "json", Schema extends z.ZodType>(target: Target, schema: Schema) =>
+const retentionInput = MailRetentionSchema.refine((value) => value.recordDays >= value.contentDays, {
+  message: "Record retention must be at least content retention.",
+  path: ["recordDays"],
+});
+
+const validate = <Target extends "param" | "json" | "query", Schema extends z.ZodType>(
+  target: Target,
+  schema: Schema,
+  code: "invalid_profile" | "bad_input" = "invalid_profile",
+) =>
   validator(target, schema, (result, c) => {
     if (!result.success) {
       const issue = result.error?.[0];
       const path = issue?.path?.map((part) => (typeof part === "object" && "key" in part ? String(part.key) : String(part))).join(".");
       return c.json(
         {
-          code: "invalid_profile" as const,
+          code,
           message: issue ? `${path ? `${path}: ` : ""}${issue.message}` : "Invalid outgoing mail configuration.",
         },
         400,
@@ -24,6 +45,52 @@ const context = (c: Context<AuthContext>): MailAuditContext => ({
   actor: { userId: c.get("user").id, uid: c.get("user").uid, provider: c.get("user").provider, roles: c.get("user").roles },
   requestId: c.req.header("x-request-id"),
 });
+const idParam = z.object({ id: z.uuid() });
+const logQuery = z
+  .object({
+    app: z.string().min(1).optional(),
+    profile: MailProfileKeySchema.optional(),
+    status: z
+      .union([z.string(), z.array(z.string())])
+      .optional()
+      .transform((value) =>
+        value === undefined ? undefined : typeof value === "string" ? value.split(",") : value.flatMap((part) => part.split(",")),
+      )
+      .pipe(z.array(MailStatusSchema).max(6).optional()),
+    since: z.iso.datetime({ offset: true }).optional(),
+    ref: z
+      .string()
+      .min(1)
+      .max(200)
+      .optional()
+      .transform((value) => {
+        if (value === undefined) return undefined;
+        const colon = value.indexOf(":");
+        return colon < 0 ? { scope: value } : { scope: value.slice(0, colon), id: value.slice(colon + 1) };
+      })
+      .pipe(z.object({ scope: z.string().min(1).max(200), id: z.string().min(1).max(200).optional() }).optional()),
+    recipient: z.string().max(320).optional(),
+    cursor: z.string().max(1024).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+  })
+  .strict();
+const logPage = z.object({
+  items: z.array(AdminMailRecordSchema),
+  page: z.int(),
+  perPage: z.int(),
+  total: z.int(),
+  hasNext: z.boolean(),
+  nextCursor: z.string().optional(),
+});
+const contentResponse = z.union([
+  z.object({ purged: z.literal(true), contentPurgedAt: z.string() }),
+  z.object({
+    purged: z.literal(false),
+    text: z.string().nullable(),
+    html: z.string().nullable(),
+    headers: z.record(z.string(), z.string()).nullable(),
+  }),
+]);
 export const createAdminOutgoingMailRoutes = (authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin")) =>
   new Hono<AuthContext>()
     .use("*", authenticate)
@@ -35,7 +102,120 @@ export const createAdminOutgoingMailRoutes = (authenticate: MiddlewareHandler<Au
       if (error instanceof OutgoingMailError) return c.json({ error: error.code, code: error.code, message: error.message }, error.status);
       throw error;
     })
+    .get(
+      "/retention",
+      describeRoute({
+        summary: "Read outgoing mail retention",
+        tags: ["Outgoing mail"],
+        ...requiresAdmin,
+        responses: { 200: jsonResponse(MailRetentionSchema, "Effective retention in days") },
+      }),
+      async (c) => c.json(await readMailRetention()),
+    )
+    .put(
+      "/retention",
+      describeRoute({
+        summary: "Update outgoing mail retention",
+        tags: ["Outgoing mail"],
+        ...requiresAdmin,
+        responses: {
+          200: jsonResponse(MailRetentionSchema, "Updated retention in days"),
+          400: jsonResponse(z.object({ code: z.literal("bad_input"), message: z.string() }), "Invalid retention"),
+        },
+      }),
+      validate("json", retentionInput, "bad_input"),
+      async (c) => {
+        const next = c.req.valid("json");
+        const old = await readMailRetention();
+        await sql.begin(async (tx) => {
+          await settings.set(MAIL_RETENTION_KEYS[0], next.contentDays, tx);
+          await settings.set(MAIL_RETENTION_KEYS[1], next.recordDays, tx);
+          await audit.record(
+            {
+              ...context(c),
+              action: "outgoing_mail.retention.update",
+              outcome: "allowed",
+              target: { type: "outgoing_mail_retention" },
+              metadata: { old, new: next },
+            },
+            tx,
+          );
+        });
+        await settings.invalidateSettingsCache(MAIL_RETENTION_KEYS);
+        return c.json(next);
+      },
+    )
+    .get(
+      "/messages",
+      describeRoute({
+        summary: "List outgoing mail metadata",
+        tags: ["Outgoing mail"],
+        ...requiresAdmin,
+        responses: { 200: jsonResponse(logPage, "Send log") },
+      }),
+      validate("query", logQuery, "bad_input"),
+      async (c) => {
+        const { cursor, limit, ...filter } = c.req.valid("query");
+        return c.json(await outgoingMailLog.list(filter, { cursor, perPage: limit }));
+      },
+    )
+    .get(
+      "/messages/:id",
+      describeRoute({
+        summary: "Read outgoing mail metadata",
+        tags: ["Outgoing mail"],
+        ...requiresAdmin,
+        responses: { 200: jsonResponse(AdminMailRecordSchema, "Message metadata") },
+      }),
+      validate("param", idParam, "bad_input"),
+      async (c) => c.json(await outgoingMailLog.get(c.req.valid("param").id)),
+    )
+    .get(
+      "/messages/:id/content",
+      describeRoute({
+        summary: "Read outgoing mail content with audit",
+        tags: ["Outgoing mail"],
+        ...requiresAdmin,
+        responses: { 200: jsonResponse(contentResponse, "Message content or purge marker") },
+      }),
+      validate("param", idParam, "bad_input"),
+      async (c) => c.json(await outgoingMailLog.content(c.req.valid("param").id, context(c))),
+    )
+    .post(
+      "/messages/:id/cancel",
+      describeRoute({
+        summary: "Cancel queued outgoing mail",
+        tags: ["Outgoing mail"],
+        ...requiresAdmin,
+        responses: {
+          200: jsonResponse(AdminMailRecordSchema, "Cancelled message"),
+          409: jsonResponse(
+            z.object({ code: z.literal("message_not_queued"), error: z.literal("message_not_queued"), message: z.string() }),
+            "Only queued mail can be cancelled",
+          ),
+        },
+      }),
+      validate("param", idParam, "bad_input"),
+      async (c) => c.json(await outgoingMailLog.cancel(c.req.valid("param").id, context(c))),
+    )
     .get("/profiles", async (c) => c.json({ items: await outgoingMailStore.list() }))
+    .post(
+      "/batches/:batchId/cancel",
+      describeRoute({
+        summary: "Cancel queued outgoing mail in a batch",
+        tags: ["Outgoing mail"],
+        ...requiresAdmin,
+        responses: {
+          200: jsonResponse(z.object({ batchId: z.uuid(), cancelled: z.int().nonnegative() }), "Cancelled queued messages"),
+          404: jsonResponse(
+            z.object({ code: z.literal("batch_unknown"), error: z.literal("batch_unknown"), message: z.string() }),
+            "Unknown batch",
+          ),
+        },
+      }),
+      validate("param", z.object({ batchId: z.uuid() }), "bad_input"),
+      async (c) => c.json(await outgoingMailLog.cancelBatch(c.req.valid("param").batchId, context(c))),
+    )
     .get("/profiles/:key", async (c) => c.json(await outgoingMailStore.get(c.req.param("key"))))
     .put(
       "/profiles/:key",

package/src/browser/FileChooser.tsx

@@ -4,6 +4,7 @@ import {
   announce,
   Button,
   createCollectionSelection,
+  FileDropTarget,
   FileGrid,
   Format,
   IconButton,
@@ -324,6 +325,16 @@ export function FileChooser(props: {
       {/* `display: contents`, so header, body, and footer stay the panel's own rows. */}
       <div ref={root} class="cloud-file-chooser">
         <PanelDialog.Header title={t().title({ multiple })} close={() => props.close([])} />
+        {/* Files dropped anywhere on the open chooser are taken like files picked from this device. */}
+        <FileDropTarget
+          label={t().dropToChoose({ multiple })}
+          accept={props.options.accept}
+          multiple={multiple}
+          disabled={downloading()}
+          onDrop={(files) => {
+            if (files.length > 0) props.close(files);
+          }}
+        />
         <div class="cloud-file-chooser__toolbar">
           <nav class="cloud-file-chooser__crumbs" aria-label={t().breadcrumbs}>
             <IconButton size="sm" variant="ghost" label={t().up} disabled={!location() || downloading()} onClick={up}>

package/src/browser/file-chooser-messages.ts

@@ -8,6 +8,7 @@ export const fileChooserMessages = i18n.define({
       sources: "Sources",
       sourceList: "Where the files come from",
       device: "This device",
+      dropToChoose: ({ multiple }: { multiple: boolean }): string => (multiple ? "Drop to add these files" : "Drop to add this file"),
       providersLoading: "Looking for apps with files…",
       providersFailed: "Apps with files could not be loaded.",
       retry: "Try again",
@@ -48,6 +49,7 @@ export const fileChooserMessages = i18n.define({
       sources: "Quellen",
       sourceList: "Woher die Dateien kommen",
       device: "Dieses Gerät",
+      dropToChoose: ({ multiple }) => (multiple ? "Ablegen, um diese Dateien hinzuzufügen" : "Ablegen, um diese Datei hinzuzufügen"),
       providersLoading: "Apps mit Dateien werden gesucht…",
       providersFailed: "Apps mit Dateien konnten nicht geladen werden.",
       retry: "Erneut versuchen",

package/src/cli/admin/index.ts

@@ -57,9 +57,11 @@ export default defineCliCommands({
     "nats consumers": "Inspect NATS consumers.",
     "nats streams": "Find NATS streams and buckets.",
     "notification-batches": "Manage account notification batches.",
-    "outgoing-mail": "Manage outgoing mail sender profiles and application access.",
+    "outgoing-mail": "Manage outgoing mail sender profiles, application access, and the send log.",
     "outgoing-mail profiles": "Manage outgoing mail sender profiles.",
     "outgoing-mail apps": "Manage application outgoing mail access.",
+    "outgoing-mail log": "Read and cancel application mail in the send log.",
+    "outgoing-mail retention": "Show or change how long the send log keeps mail.",
     notifications: "Inspect and resend email notifications.",
     postgres: "Inspect Postgres diagnostics.",
     redis: "Inspect Valkey diagnostics.",

package/src/cli/admin/notifications.ts

@@ -54,6 +54,8 @@ export type NotificationBatchRecipient = {
   profile: "user" | "guest";
   status: NotificationRecipientStatus;
   notificationId: string | null;
+  outgoingMailId: string | null;
+  outgoingMailStatus: string | null;
   error: string | null;
   attemptCount: number;
   sentAt: string | null;
@@ -370,6 +372,8 @@ export const notificationCommands = [
         provider: recipient.provider,
         profile: recipient.profile,
         attempts: recipient.attemptCount,
+        mailId: recipient.outgoingMailId ?? "",
+        mailStatus: recipient.outgoingMailStatus ?? "",
         error: truncate(recipient.error, 60),
         userId: recipient.userId,
       }));
@@ -381,6 +385,8 @@ export const notificationCommands = [
         { key: "provider" },
         { key: "profile" },
         { key: "attempts" },
+        { key: "mailId" },
+        { key: "mailStatus" },
         { key: "error" },
         { key: "userId" },
       ]);

package/src/cli/admin/outgoing-mail.ts

@@ -1,5 +1,13 @@
-import { type AdminMailApp, type AdminMailProfile, MailProfileInputSchema } from "../../contracts/outgoing-mail";
-import { arg, type CloudCliContext, command, confirmFlag, flag, readCliInput } from "../index";
+import {
+  type AdminMailApp,
+  type AdminMailProfile,
+  type AdminMailRecord,
+  type MailPage,
+  MailProfileInputSchema,
+  type MailRetention,
+  MailRetentionSchema,
+} from "../../contracts/outgoing-mail";
+import { arg, type CloudCliContext, command, confirmFlag, flag, printStructured, readCliInput } from "../index";
 import { apiGet, apiJson, printJsonOrTable } from "./shared";
 
 const root = "/api/admin/core/outgoing-mail";
@@ -13,6 +21,78 @@ const confirmed = (yes: boolean) => {
   if (!yes) throw new Error("Outgoing mail policy changes require --yes.");
 };
 export const outgoingMailCommands = [
+  command("outgoing-mail retention show", {
+    summary: "Show outgoing mail retention in days",
+    async run({ ctx }) {
+      const result = await apiGet<MailRetention>(ctx, `${root}/retention`);
+      if (!printStructured(ctx, result)) print(ctx, result);
+    },
+  }),
+  command("outgoing-mail retention set", {
+    summary: "Set outgoing mail content and record retention",
+    flags: {
+      contentDays: flag.string({ required: true, description: "Content retention in days" }),
+      recordDays: flag.string({ required: true, description: "Record retention in days (at least content retention)" }),
+      yes: confirmFlag("Confirm changing outgoing mail retention"),
+    },
+    async run({ ctx, flags }) {
+      confirmed(flags.yes);
+      const retention = MailRetentionSchema.parse({ contentDays: Number(flags.contentDays), recordDays: Number(flags.recordDays) });
+      if (retention.recordDays < retention.contentDays) throw new Error("Record retention must be at least content retention.");
+      const result = await apiJson<MailRetention>(ctx, "PUT", `${root}/retention`, retention);
+      if (!printStructured(ctx, result)) print(ctx, result);
+    },
+  }),
+  command("outgoing-mail log list", {
+    summary: "List outgoing mail metadata",
+    flags: {
+      app: flag.string({ description: "Application ID" }),
+      profile: flag.string({ description: "Sender profile key" }),
+      status: flag.string({ description: "Comma-separated statuses" }),
+      since: flag.string({ description: "ISO timestamp" }),
+      ref: flag.string({ description: "Reference scope[:id]" }),
+      recipient: flag.string({ description: "Recipient substring" }),
+      cursor: flag.string({ description: "Next-page cursor" }),
+      limit: flag.int({ description: "Page size (1–100)" }),
+    },
+    async run({ ctx, flags }) {
+      if (flags.limit !== undefined && (!Number.isInteger(flags.limit) || flags.limit < 1 || flags.limit > 100))
+        throw new Error("--limit must be a whole number from 1 to 100.");
+      const query = new URLSearchParams();
+      for (const [key, value] of Object.entries(flags)) if (value !== undefined) query.set(key, String(value));
+      const result = await apiGet<MailPage<AdminMailRecord>>(ctx, `${root}/messages${query.size ? `?${query}` : ""}`);
+      printJsonOrTable(ctx, result, result.items, [
+        { key: "id" },
+        { key: "appId" },
+        { key: "profile" },
+        { key: "status" },
+        { key: "createdAt" },
+      ]);
+      if (ctx.options.output === "text" && result.nextCursor) ctx.print(`Next cursor: ${result.nextCursor}`);
+    },
+  }),
+  command("outgoing-mail log show", {
+    summary: "Read outgoing mail metadata, or audited content",
+    args: { id: arg.required({ valueLabel: "id" }) },
+    flags: { content: flag.boolean({ description: "Read message content (audited)" }) },
+    async run({ ctx, args, flags }) {
+      print(ctx, await apiGet(ctx, `${root}/messages/${encodeURIComponent(args.id)}${flags.content ? "/content" : ""}`));
+    },
+  }),
+  command("outgoing-mail log cancel", {
+    summary: "Cancel queued outgoing mail",
+    args: { id: arg.optional({ valueLabel: "id" }) },
+    flags: {
+      batch: flag.string({ description: "Cancel queued messages in this batch instead of one ID" }),
+      yes: confirmFlag("Confirm cancelling queued outgoing mail"),
+    },
+    async run({ ctx, args, flags }) {
+      if (!flags.yes) throw new Error("Cancelling outgoing mail requires --yes.");
+      if ((args.id !== undefined) === (flags.batch !== undefined)) throw new Error("Choose exactly one message ID or --batch <batchId>.");
+      const path = flags.batch !== undefined ? `batches/${encodeURIComponent(flags.batch)}` : `messages/${encodeURIComponent(args.id!)}`;
+      print(ctx, await apiJson(ctx, "POST", `${root}/${path}/cancel`));
+    },
+  }),
   command("outgoing-mail profiles list", {
     summary: "List outgoing mail sender profiles",
     async run({ ctx }) {
@@ -20,8 +100,16 @@ export const outgoingMailCommands = [
       printJsonOrTable(
         ctx,
         result,
-        result.items.map((p) => ({ key: p.key, name: p.name, from: p.fromAddress, default: p.isDefault, revision: p.revision })),
-        [{ key: "key" }, { key: "name" }, { key: "from" }, { key: "default" }, { key: "revision" }],
+        result.items.map((p) => ({
+          key: p.key,
+          name: p.name,
+          from: p.fromAddress,
+          default: p.isDefault,
+          revision: p.revision,
+          imap: p.imap ? `${p.imap.host}/${p.imap.folder}` : "off",
+          bounces: p.bounces ? (p.bounces.error ?? p.bounces.checkedAt ?? "pending") : "off",
+        })),
+        [{ key: "key" }, { key: "name" }, { key: "from" }, { key: "default" }, { key: "revision" }, { key: "imap" }, { key: "bounces" }],
       );
     },
   }),
@@ -29,13 +117,18 @@ export const outgoingMailCommands = [
     summary: "Read one outgoing mail sender profile",
     args: keyArgs,
     async run({ ctx, args }) {
-      print(ctx, await apiGet(ctx, profilePath(args.key)));
+      const profile = await apiGet<AdminMailProfile>(ctx, profilePath(args.key));
+      print(ctx, profile);
+      if (ctx.options.output === "text")
+        ctx.print(`Bounces: ${profile.bounces ? (profile.bounces.error ?? profile.bounces.checkedAt ?? "pending") : "off"}`);
     },
   }),
   command("outgoing-mail profiles put", {
     summary: "Create or replace a sender profile with its current revision",
     args: keyArgs,
-    flags: { config: flag.input({ required: true, description: "Profile JSON; SMTP passwords only via --config-file or --stdin" }) },
+    flags: {
+      config: flag.input({ required: true, description: "Profile JSON; SMTP and IMAP passwords only via --config-file or --stdin" }),
+    },
     async run({ ctx, args, flags }) {
       const input = await readCliInput(flags.config, { label: "outgoing mail profile", required: true });
       let raw: unknown;
@@ -46,7 +139,11 @@ export const outgoingMailCommands = [
       }
       if (flags.config.source === "value" && raw && typeof raw === "object" && "smtpPassword" in raw)
         throw new Error("Pass smtpPassword only through --config-file or --stdin.");
-      print(ctx, await apiJson(ctx, "PUT", profilePath(args.key), MailProfileInputSchema.parse(raw)));
+      const parsed = MailProfileInputSchema.safeParse(raw);
+      if (!parsed.success) throw new Error("Invalid outgoing mail profile configuration.");
+      if (flags.config.source === "value" && parsed.data.imap && "password" in parsed.data.imap)
+        throw new Error("Pass imap.password only through --config-file or --stdin.");
+      print(ctx, await apiJson(ctx, "PUT", profilePath(args.key), parsed.data));
     },
   }),
   command("outgoing-mail profiles set-default", {

package/src/contracts/outgoing-mail.ts

@@ -1,7 +1,12 @@
+import type { PageParams, Paginated, ServiceError } from "@k2b/stdlib";
 import { z } from "zod";
+import { type RequestActor, ServiceAccountSchema, UserSchema } from "./shared";
 
 export const PlatformPermissionSchema = z.enum(["mail:send"]);
 export type PlatformPermission = z.infer<typeof PlatformPermissionSchema>;
+export const MailRetentionSchema = z.object({ contentDays: z.int().min(1).max(36500), recordDays: z.int().min(1).max(36500) }).strict();
+export type MailRetention = z.infer<typeof MailRetentionSchema>;
+
 export const MailProfileKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,62}$/);
 const headerText = z
   .string()
@@ -9,6 +14,26 @@ const headerText = z
   .min(1)
   .max(120)
   .refine((value) => !/[\r\n\0]/.test(value), "Header must not contain control characters");
+export const MailImapInputSchema = z
+  .object({
+    host: z
+      .string()
+      .trim()
+      .min(1)
+      .max(253)
+      .refine((value) => !/[\s/@\0]/.test(value), "Use an IMAP hostname"),
+    port: z.int().min(1).max(65535),
+    secure: z.boolean(),
+    user: z.string().trim().min(1).max(320),
+    password: z.string().max(16384).nullable().optional(),
+    folder: z
+      .string()
+      .trim()
+      .min(1)
+      .max(200)
+      .refine((value) => !/[\x00-\x1f\x7f]/.test(value), "Folder must not contain control characters"),
+  })
+  .strict();
 export const MailProfileInputSchema = z
   .object({
     name: headerText,
@@ -24,6 +49,7 @@ export const MailProfileInputSchema = z
     smtpSecure: z.boolean(),
     smtpUser: z.string().max(320).nullable(),
     smtpPassword: z.string().max(16384).nullable().optional(),
+    imap: MailImapInputSchema.nullable().optional(),
     pacePerMinute: z.int().min(1).max(6000),
     dailyRecipientLimit: z.int().min(1).max(2147483647).nullable(),
     maxAttachmentBytes: z.int().min(1).max(26214400),
@@ -46,6 +72,19 @@ export const MailProfileSchema = z.object({
 });
 export type MailProfile = z.infer<typeof MailProfileSchema>;
 export const MailErrorCodeSchema = z.enum([
+  "bad_input",
+  "profile_not_allowed",
+  "profile_required",
+  "quota_exceeded",
+  "backlog_full",
+  "attachments_too_large",
+  "attachment_storage_full",
+  "profile_removed",
+  "attachment_lost",
+  "cancelled_by_admin",
+  "message_unknown",
+  "batch_unknown",
+  "message_not_queued",
   "mail_unavailable",
   "mail_not_declared",
   "profile_unknown",
@@ -56,9 +95,13 @@ export const MailErrorCodeSchema = z.enum([
   "smtp_failed",
 ]);
 export type MailErrorCode = z.infer<typeof MailErrorCodeSchema>;
-export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true }).extend({
+export const MailBounceErrorCodeSchema = z.enum(["open_failed", "search_failed", "apply_failed", "save_failed", "interrupted"]);
+export type MailBounceErrorCode = z.infer<typeof MailBounceErrorCodeSchema>;
+export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true, imap: true }).extend({
   key: MailProfileKeySchema,
   hasPassword: z.boolean(),
+  imap: MailImapInputSchema.omit({ password: true }).extend({ hasPassword: z.boolean() }).nullable(),
+  bounces: z.object({ checkedAt: z.string().nullable(), error: MailBounceErrorCodeSchema.nullable() }).nullable(),
   isDefault: z.boolean(),
   revision: z.int(),
   createdAt: z.string(),
@@ -75,3 +118,148 @@ export type AdminMailApp = {
   mode: "default" | "selected";
   profiles: string[];
 };
+
+export const MailStatusSchema = z.enum(["queued", "sending", "sent", "failed", "bounced", "cancelled"]);
+export type MailStatus = z.infer<typeof MailStatusSchema>;
+export type MailAttachment = {
+  filename: string;
+  contentType: string;
+  content: Uint8Array | Blob | ReadableStream<Uint8Array>;
+};
+const body = z
+  .string()
+  .refine((value) => !value.includes("\0"), "Body must not contain NUL")
+  .max(512 * 1024)
+  .refine((value) => new TextEncoder().encode(value).byteLength <= 512 * 1024, "Body exceeds 512 KiB");
+const safeHeader = z.string().refine((value) => !/[\r\n\0]/.test(value), "Header must not contain control characters");
+const allowedHeaders = new Set([
+  "list-id",
+  "list-unsubscribe",
+  "list-unsubscribe-post",
+  "in-reply-to",
+  "references",
+  "auto-submitted",
+  "precedence",
+]);
+export const MailHeadersSchema = z.record(z.string(), safeHeader).refine((headers) => {
+  let bytes = 0;
+  const seen = new Set<string>();
+  for (const [name, value] of Object.entries(headers)) {
+    const lower = name.toLowerCase();
+    if (!/^[\x21-\x39\x3B-\x7E]+$/.test(name) || seen.has(lower)) return false;
+    seen.add(lower);
+    if (!(lower.startsWith("x-") && !lower.startsWith("x-cloud-")) && !allowedHeaders.has(lower)) return false;
+    bytes += new TextEncoder().encode(`${name}: ${value}\r\n`).byteLength;
+  }
+  return bytes <= 8192;
+}, "Invalid mail headers or headers exceed 8 KiB");
+const referenceText = z
+  .string()
+  .min(1)
+  .max(200)
+  .refine((value) => !value.includes("\0"), "Reference must not contain NUL");
+const ref = z.object({ scope: referenceText, id: referenceText }).strict();
+const mailAddress = z.email({ pattern: z.regexes.html5Email }).max(320);
+export const MailMessageSchema = z
+  .object({
+    to: z.array(mailAddress).min(1).max(50),
+    subject: safeHeader.max(998),
+    text: body,
+    html: body.optional(),
+    fromName: safeHeader.max(998).optional(),
+    replyTo: mailAddress.optional(),
+    attachments: z
+      .array(
+        z
+          .object({
+            filename: safeHeader.min(1).max(998),
+            contentType: safeHeader.min(1).max(998),
+            content: z.custom<MailAttachment["content"]>(
+              (value) => value instanceof Uint8Array || value instanceof Blob || value instanceof ReadableStream,
+            ),
+          })
+          .strict(),
+      )
+      .max(20)
+      .optional(),
+    headers: MailHeadersSchema.optional(),
+    profile: MailProfileKeySchema.optional(),
+    ref: ref.optional(),
+    actor: z
+      .custom<RequestActor>((value) => {
+        if (!value || typeof value !== "object" || !("kind" in value)) return false;
+        if (value.kind === "user" && "user" in value) return UserSchema.safeParse(value.user).success;
+        return (
+          value.kind === "service_account" && "serviceAccount" in value && ServiceAccountSchema.safeParse(value.serviceAccount).success
+        );
+      })
+      .optional(),
+    key: z
+      .string()
+      .min(1)
+      .max(200)
+      .refine((value) => !value.includes("\0"), "Key must not contain NUL")
+      .optional(),
+  })
+  .strict();
+export type MailMessage = z.infer<typeof MailMessageSchema>;
+export const MailBatchSchema = z
+  .array(MailMessageSchema)
+  .min(1)
+  .max(1000)
+  .refine((messages) => {
+    const keys = messages.flatMap((message) => (message.key === undefined ? [] : [message.key]));
+    return new Set(keys).size === keys.length;
+  }, "Duplicate outgoing mail keys in a batch");
+export const MailFilterSchema = z
+  .object({
+    ref: ref.partial({ id: true }).optional(),
+    ids: z.array(z.uuid()).max(100).optional(),
+    batchId: z.uuid().optional(),
+    status: z.array(MailStatusSchema).max(6).optional(),
+    since: z.iso.datetime({ offset: true }).optional(),
+  })
+  .strict();
+export type MailFilter = z.infer<typeof MailFilterSchema>;
+export const MailRecordSchema = z.object({
+  id: z.uuid(),
+  batchId: z.uuid().optional(),
+  profile: z.string(),
+  ref: ref.optional(),
+  to: z.array(z.string()),
+  subject: z.string(),
+  text: z.string().optional(),
+  attachments: z.array(z.object({ filename: z.string(), contentType: z.string(), size: z.int().nonnegative(), sha256: z.string() })),
+  status: MailStatusSchema,
+  error: z.string().optional(),
+  failures: z.array(z.object({ recipient: z.string(), reason: z.string(), at: z.string() })),
+  attempts: z.int(),
+  actor: z.object({ id: z.string(), name: z.string() }).optional(),
+  createdAt: z.string(),
+  sentAt: z.string().optional(),
+  contentPurgedAt: z.string().optional(),
+});
+export type MailRecord = z.infer<typeof MailRecordSchema>;
+export const AdminMailRecordSchema = MailRecordSchema.omit({ text: true }).extend({
+  appId: z.string(),
+  errorCode: z.string().optional(),
+  response: z.string().optional(),
+});
+export type AdminMailRecord = z.infer<typeof AdminMailRecordSchema>;
+/** Extends the shared offset-page shape with stable keyset navigation. */
+export type MailPageParams = PageParams & { cursor?: string };
+export type MailPage<T = MailRecord> = Paginated<T> & { nextCursor?: string };
+export const MailPageParamsSchema = z
+  .object({ page: z.int().min(1).optional(), perPage: z.int().min(1).max(100).optional(), cursor: z.string().max(1024).optional() })
+  .strict();
+export const AdminMailFilterSchema = MailFilterSchema.extend({
+  app: z.string().min(1).optional(),
+  profile: MailProfileKeySchema.optional(),
+  recipient: z.string().max(320).optional(),
+});
+export type AdminMailFilter = z.infer<typeof AdminMailFilterSchema>;
+export type MailServiceError = ServiceError<MailErrorCode> & {
+  limit?: number;
+  used?: number;
+  requested?: number;
+};