@k2b/cloud 0.26.0 → 0.28.0

package/src/contracts/app.ts

@@ -1,4 +1,5 @@
 import type { Sync } from "@k2b/sync";
+import type { PlatformPermission } from "./outgoing-mail";
 import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
@@ -97,6 +98,7 @@ export type AppPwaPart = {
 };
 
 export type AppMeta = {
+  platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;
   icon: string;

package/src/contracts/index.ts

@@ -8,6 +8,7 @@ export * from "./commands";
 export * from "./contact-directory";
 export * from "./file-provider";
 export * from "./notification-types";
+export * from "./outgoing-mail";
 export * from "./posix";
 export * from "./profile";
 export * from "./pwa";

package/src/contracts/outgoing-mail.ts

@@ -0,0 +1,265 @@
+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()
+  .trim()
+  .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,
+    fromAddress: z.email().max(320),
+    fromName: headerText.nullable(),
+    smtpHost: z
+      .string()
+      .trim()
+      .min(1)
+      .max(253)
+      .refine((value) => !/[\s/@\0]/.test(value), "Use an SMTP hostname"),
+    smtpPort: z.int().min(1).max(65535),
+    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),
+    revision: z.int().min(1).max(2147483647).optional(),
+  })
+  .strict();
+export type MailProfileInput = z.infer<typeof MailProfileInputSchema>;
+export const MailAppAccessSchema = z.discriminatedUnion("mode", [
+  z.object({ mode: z.literal("default") }).strict(),
+  z.object({ mode: z.literal("selected"), profiles: z.array(MailProfileKeySchema) }).strict(),
+]);
+export type MailAppAccess = z.infer<typeof MailAppAccessSchema>;
+export const MailProfileSchema = z.object({
+  key: MailProfileKeySchema,
+  name: z.string(),
+  from: z.email(),
+  default: z.boolean(),
+  maxAttachmentBytes: z.int(),
+  quota: z.object({ dailyRecipients: z.int().nullable(), usedLast24h: z.int() }),
+});
+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",
+  "profile_exists",
+  "profile_is_default",
+  "revision_conflict",
+  "invalid_profile",
+  "smtp_failed",
+]);
+export type MailErrorCode = z.infer<typeof MailErrorCodeSchema>;
+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(),
+  updatedAt: z.string(),
+  updatedBy: z.string().nullable(),
+  appCount: z.int(),
+});
+export type AdminMailProfile = z.infer<typeof AdminMailProfileSchema>;
+export type AdminMailApp = {
+  appId: string;
+  name: string;
+  registered: boolean;
+  declared: boolean;
+  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;
+};

package/src/contracts/registry.ts

@@ -1,5 +1,6 @@
 import type { AppAdminNavigationGroup, AppAppearance, AppAppearanceColor, AppPresentationCatalog, AppSearchLink } from "./app";
 import type { CapabilityManifest, CapabilityPresentationCatalog } from "./capabilities";
+import type { PlatformPermission } from "./outgoing-mail";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
 
@@ -65,6 +66,7 @@ export type AppRuntimeMetadata = {
 };
 
 export type AppRegistryEntry = {
+  platformPermissions?: readonly PlatformPermission[];
   id: string;
   name: string;
   icon: string;

package/src/services/help/store.ts

@@ -1,5 +1,6 @@
 import { type SQL, sql } from "bun";
 import { APP_REGISTRY_TTL_MS } from "../../_internal/registry";
+import { ensureSchema } from "../postgres";
 import type { HelpCorpus, HelpMetadata } from "./types";
 
 // One expired app lease of grace after an app can no longer be discovered.
@@ -10,7 +11,7 @@ const searchConfigs = ["english", "german", "simple"] as const;
 export const migrateHelp = async (db: SQL = sql): Promise<void> => {
   await db.begin(async (tx) => {
     await tx`SELECT pg_advisory_xact_lock(hashtext('cloud:help:migrate'))`;
-    await tx`CREATE SCHEMA IF NOT EXISTS help`.simple();
+    await ensureSchema(tx, "help");
     await tx`CREATE TABLE IF NOT EXISTS help.corpora (
     app_id text NOT NULL, manifest_hash text NOT NULL, base_locale text NOT NULL,
     last_seen_at timestamptz NOT NULL DEFAULT now(),

package/src/services/index.ts

@@ -204,3 +204,16 @@ export { legalConsent } from "./legal-consent";
 export { railShortcuts } from "./rail-shortcuts";
 
 export type { WebVitalsOverview, WebVitalsQuery, WebVitalMetric, WebVitalName } from "./logging/web-vitals";
+
+export { mail } from "./outgoing-mail";
+export type {
+  MailProfile,
+  MailAttachment,
+  MailMessage,
+  MailFilter,
+  MailRecord,
+  MailStatus,
+  MailPageParams,
+  MailPage,
+  MailServiceError,
+} from "../contracts/outgoing-mail";

package/src/services/notifications/batches.ts

@@ -3,12 +3,15 @@ import { err, fail, ok, type Result } from "@k2b/stdlib";
 import type { Worker } from "@k2b/sync";
 import { sql } from "bun";
 import { lazySync } from "../../_internal/process-sync";
+import { type MailMessage, MailMessageSchema, type MailStatus, MailStatusSchema } from "../../contracts/outgoing-mail";
 import { markdown } from "../../shared/markdown";
 import { type AuditActor, audit } from "../audit";
 import { logger, trace } from "../logging";
+import { enqueueMail } from "../outgoing-mail/enqueue";
+import { outgoingMailStore } from "../outgoing-mail/store";
 import { parsePgJsonValue, toPgTextArray, toPgUuidArray } from "../postgres";
-
-import { sendEmail } from "./email";
+import { prepareNotificationEmail } from "./email-frame";
+import { normalizeNotificationMail, notificationMailError, notificationMailValidationError } from "./email-mail";
 
 const log = logger("notifications:batches");
 const CHUNK_SIZE = 100;
@@ -64,6 +67,8 @@ export type NotificationBatchRecipient = {
   profile: "user" | "guest";
   status: NotificationBatchRecipientStatus;
   notificationId: string | null;
+  outgoingMailId: string | null;
+  outgoingMailStatus: MailStatus | null;
   error: string | null;
   attemptCount: number;
   sentAt: string | null;
@@ -163,6 +168,8 @@ const mapRecipient = (row: BatchRow): NotificationBatchRecipient => ({
   profile: row.profile as "user" | "guest",
   status: row.status as NotificationBatchRecipientStatus,
   notificationId: row.notification_id as string | null,
+  outgoingMailId: typeof row.outgoing_mail_id === "string" ? row.outgoing_mail_id : null,
+  outgoingMailStatus: MailStatusSchema.nullable().parse(row.outgoing_mail_status ?? null),
   error: row.error as string | null,
   attemptCount: Number(row.attempt_count ?? 0),
   sentAt: row.sent_at ? (row.sent_at as Date).toISOString() : null,
@@ -210,29 +217,6 @@ const resolveCandidates = async (rawSelection: NotificationBatchSelection): Prom
   `;
 };
 
-const sendBatchEmail = async (params: {
-  recipient: string;
-  subject: string;
-  rawHtml: string;
-  sentBy?: string;
-}): Promise<{ id: string; status: "sent" | "error"; error?: string }> => {
-  const rows = await sql<BatchRow[]>`
-    INSERT INTO notifications.messages (type, recipient, subject, content, sent_by)
-    VALUES ('email', ${params.recipient}, ${params.subject}, ${params.rawHtml}, ${params.sentBy ?? null})
-    RETURNING id
-  `;
-  const id = rows[0]!.id as string;
-  try {
-    await sendEmail(params.recipient, params.subject, { rawHtml: params.rawHtml });
-    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}::uuid`;
-    return { id, status: "sent" };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    await sql`UPDATE notifications.messages SET error = ${message} WHERE id = ${id}::uuid`;
-    return { id, status: "error", error: message };
-  }
-};
-
 export const preview = async (selection: NotificationBatchSelection): Promise<NotificationBatchPreview> => {
   const candidates = await resolveCandidates(selection);
   return {
@@ -286,74 +270,147 @@ const refreshBatchCounters = async (batchId: string): Promise<NotificationBatch
 };
 
 const processBatchChunk = async (batchId: string): Promise<{ processed: number; remaining: number }> => {
-  await sql`
+  const [batchRow] = await sql<BatchRow[]>`
     UPDATE notifications.batches
     SET status = 'running', started_at = COALESCE(started_at, now())
     WHERE id = ${batchId}::uuid AND status IN ('ready', 'running')
+    RETURNING *
   `;
+  if (!batchRow) return { processed: 0, remaining: 0 };
+  const batch = mapBatch(batchRow);
 
-  const recipients = await sql<BatchRow[]>`
-    UPDATE notifications.batch_recipients r
-    SET status = 'sending', attempt_count = attempt_count + 1, updated_at = now()
-    WHERE (r.batch_id, r.user_id) IN (
-      SELECT batch_id, user_id
-      FROM notifications.batch_recipients
-      WHERE batch_id = ${batchId}::uuid
-        AND recipient IS NOT NULL
-        AND (
-          status = 'pending'
-          OR (status = 'sending' AND updated_at < now() - interval '5 minutes')
-        )
-      ORDER BY updated_at ASC
-      LIMIT ${CHUNK_SIZE}
-      FOR UPDATE SKIP LOCKED
+  // Settle a bounded page and its legacy message history in the same statement.
+  const settled = await sql<{ id: string }[]>`
+    WITH terminal AS (
+      SELECT r.user_id, r.outgoing_mail_id, m.status, m.sent_at, COALESCE(m.error_message, m.smtp_response, 'Outgoing mail ' || m.status, 'Outgoing mail record is no longer available.') AS error
+      FROM notifications.batch_recipients r
+      LEFT JOIN outgoing_mail.messages m ON m.id = r.outgoing_mail_id
+      WHERE r.batch_id = ${batchId}::uuid AND r.status = 'sending' AND r.outgoing_mail_id IS NOT NULL
+        AND (m.status IN ('sent', 'bounced', 'failed', 'cancelled') OR m.id IS NULL)
+      ORDER BY r.user_id LIMIT ${CHUNK_SIZE}
+    ), settled AS (
+      UPDATE notifications.batch_recipients r
+      SET status = CASE WHEN t.status IN ('sent', 'bounced') THEN 'sent' ELSE 'error' END,
+          sent_at = CASE WHEN t.status IN ('sent', 'bounced') THEN COALESCE(t.sent_at, now()) ELSE NULL END,
+          error = CASE WHEN t.status IN ('sent', 'bounced') THEN NULL ELSE t.error END, updated_at = now()
+      FROM terminal t
+      WHERE r.batch_id = ${batchId}::uuid AND r.user_id = t.user_id AND r.status = 'sending'
+        AND r.outgoing_mail_id = t.outgoing_mail_id
+      RETURNING r.notification_id, r.sent_at, r.error
     )
-    RETURNING r.*
+    UPDATE notifications.messages m SET sent_at = s.sent_at, error = s.error
+    FROM settled s WHERE m.id = s.notification_id AND m.mail_generation = 0 RETURNING m.id
   `;
 
-  const [batchRow] = await sql<BatchRow[]>`SELECT * FROM notifications.batches WHERE id = ${batchId}::uuid`;
-  if (!batchRow || batchRow.status === "cancelled") return { processed: 0, remaining: 0 };
-  const batch = mapBatch(batchRow);
+  const profile = (await outgoingMailStore.profilesForApp("core")).find((profile) => profile.default);
+  const claimSize =
+    profile?.quota.dailyRecipients == null
+      ? CHUNK_SIZE
+      : Math.max(0, Math.min(CHUNK_SIZE, profile.quota.dailyRecipients - profile.quota.usedLast24h));
+
+  type ClaimedRecipient = { user_id: string; recipient: string; notification_id: string | null };
+  // Persist a send generation before any external effect. Reclaim and worker
+  // retries reuse it; operator retries clear it and create a new generation.
+  const recipients = await sql.begin(async (tx) => {
+    const rows = await tx<ClaimedRecipient[]>`
+      UPDATE notifications.batch_recipients r
+      SET status = 'sending', attempt_count = attempt_count + 1, updated_at = now()
+      WHERE (r.batch_id, r.user_id) IN (
+        SELECT batch_id, user_id FROM notifications.batch_recipients
+        WHERE batch_id = ${batchId}::uuid AND recipient IS NOT NULL AND outgoing_mail_id IS NULL
+          AND (status = 'pending' OR (status = 'sending' AND updated_at < now() - interval '5 minutes'))
+        ORDER BY updated_at ASC LIMIT ${claimSize} FOR UPDATE SKIP LOCKED
+      )
+      RETURNING r.user_id, r.recipient, r.notification_id
+    `;
+    for (const row of rows) {
+      if (row.notification_id) continue;
+      const [message] = await tx<{ id: string }[]>`
+        INSERT INTO notifications.messages (type, recipient, subject, content, sent_by)
+        VALUES ('email', ${row.recipient}, ${batch.subject}, ${batch.bodyHtml}, ${batch.finalizedBy ?? batch.createdBy}::uuid)
+        RETURNING id
+      `;
+      if (!message) throw new Error("Notification batch message insert returned no row");
+      row.notification_id = message.id;
+      await tx`UPDATE notifications.batch_recipients SET notification_id = ${message.id}::uuid
+        WHERE batch_id = ${batchId}::uuid AND user_id = ${row.user_id}::uuid`;
+    }
+    return rows;
+  });
 
-  for (const recipient of recipients) {
+  const failRecipients = async (rows: ClaimedRecipient[], failure: ReturnType<typeof notificationMailError>) => {
+    const generations = toPgUuidArray(rows.flatMap((recipient) => (recipient.notification_id ? [recipient.notification_id] : [])));
+    await sql`
+      WITH changed AS (
+        UPDATE notifications.batch_recipients
+        SET status = ${failure.retryable ? "pending" : "error"}, error = ${failure.retryable ? null : failure.message}, updated_at = now()
+        WHERE batch_id = ${batchId}::uuid AND notification_id = ANY(${generations}::uuid[])
+          AND status = 'sending' AND outgoing_mail_id IS NULL
+        RETURNING notification_id, error
+      )
+      UPDATE notifications.messages m SET error = c.error FROM changed c WHERE m.id = c.notification_id
+    `;
+  };
+  let invalidCount = 0;
+  if (recipients.length) {
     try {
-      const result = await sendBatchEmail({
-        recipient: recipient.recipient as string,
-        subject: batch.subject,
-        rawHtml: batch.bodyHtml,
-        sentBy: batch.finalizedBy ?? batch.createdBy ?? undefined,
+      const frame = await prepareNotificationEmail({ rawHtml: batch.bodyHtml });
+      const shared = MailMessageSchema.pick({ subject: true, text: true, html: true }).safeParse({
+        subject: normalizeNotificationMail("", batch.subject).subject,
+        ...frame,
       });
-      await sql`
-        UPDATE notifications.batch_recipients
-        SET
-          status = ${result.status === "sent" ? "sent" : "error"},
-          notification_id = ${result.id}::uuid,
-          error = NULL,
-          sent_at = ${result.status === "sent" ? sql`now()` : null},
-          updated_at = now()
-        WHERE batch_id = ${batchId}::uuid AND user_id = ${recipient.user_id}::uuid
-      `;
+      if (!shared.success) throw notificationMailValidationError(shared.error);
+      const valid: { recipient: ClaimedRecipient; message: MailMessage }[] = [];
+      for (const recipient of recipients) {
+        const parsed = MailMessageSchema.safeParse({
+          ...normalizeNotificationMail(recipient.recipient, shared.data.subject),
+          ...shared.data,
+          key: `notification-message:${recipient.notification_id}`,
+        });
+        if (!parsed.success) {
+          await failRecipients([recipient], notificationMailError(notificationMailValidationError(parsed.error)));
+          invalidCount++;
+        } else valid.push({ recipient, message: parsed.data });
+      }
+      if (valid.length) {
+        const accepted = await enqueueMail(
+          "core",
+          valid.map(({ message }) => message),
+          { trustedHtml: true },
+        );
+        for (const [index, { recipient }] of valid.entries()) {
+          await sql`
+            WITH linked AS (
+              UPDATE notifications.batch_recipients SET outgoing_mail_id = ${accepted.ids[index]}::uuid, updated_at = now()
+              WHERE batch_id = ${batchId}::uuid AND user_id = ${recipient.user_id}::uuid
+                AND notification_id = ${recipient.notification_id}::uuid AND status = 'sending' AND outgoing_mail_id IS NULL
+              RETURNING notification_id, outgoing_mail_id
+            )
+            UPDATE notifications.messages m SET outgoing_mail_id = l.outgoing_mail_id
+            FROM linked l WHERE m.id = l.notification_id AND m.mail_generation = 0
+          `;
+        }
+      }
     } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      log.error("Batch recipient send failed", { batchId, userId: recipient.user_id, error: message });
-      await sql`
-        UPDATE notifications.batch_recipients
-        SET status = 'error', error = ${message}, updated_at = now()
-        WHERE batch_id = ${batchId}::uuid AND user_id = ${recipient.user_id}::uuid
-      `;
+      const failure = notificationMailError(error);
+      log.error("Notification batch enqueue failed", { batchId, code: failure.code, error: failure.message });
+      await failRecipients(recipients, failure);
+      // Backlog/quota/storage failures are not terminal recipient failures.
+      await refreshBatchCounters(batchId);
+      return { processed: invalidCount + settled.length, remaining: await remainingBatchRecipients(batchId) };
     }
   }
+  const remaining = await remainingBatchRecipients(batchId);
+  await refreshBatchCounters(batchId);
+  return { processed: recipients.length + settled.length, remaining };
+};
 
-  const [pendingRow] = await sql<BatchRow[]>`
-    SELECT COUNT(*)::int AS count
-    FROM notifications.batch_recipients
-    WHERE batch_id = ${batchId}::uuid
-      AND recipient IS NOT NULL
-      AND status IN ('pending', 'sending')
+const remainingBatchRecipients = async (batchId: string): Promise<number> => {
+  const [row] = await sql<{ count: number }[]>`
+    SELECT COUNT(*)::int AS count FROM notifications.batch_recipients
+    WHERE batch_id = ${batchId}::uuid AND recipient IS NOT NULL AND status IN ('pending', 'sending')
   `;
-  const remaining = Number(pendingRow?.count ?? 0);
-  await refreshBatchCounters(batchId);
-  return { processed: recipients.length, remaining };
+  return row?.count ?? 0;
 };
 
 const batchJob = lazySync((sync) => {
@@ -492,6 +549,8 @@ export const listRecipients = async (params: {
       r.profile,
       r.status,
       r.notification_id,
+      r.outgoing_mail_id,
+      mail.status AS outgoing_mail_status,
       COALESCE(m.error, r.error) AS error,
       r.attempt_count,
       r.sent_at,
@@ -499,6 +558,7 @@ export const listRecipients = async (params: {
       COUNT(*) OVER() AS total
     FROM notifications.batch_recipients r
     LEFT JOIN notifications.messages m ON m.id = r.notification_id
+    LEFT JOIN outgoing_mail.messages mail ON mail.id = r.outgoing_mail_id
     LEFT JOIN auth.users u ON u.id = r.user_id
     WHERE r.batch_id = ${params.batchId}::uuid
       AND (${params.status ?? null}::text IS NULL OR r.status = ${params.status ?? null})
@@ -620,7 +680,7 @@ export const retryFailed = async (params: {
   const result = await sql.begin(async (tx) => {
     const updated = await tx<BatchRow[]>`
       UPDATE notifications.batch_recipients
-      SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
+      SET status = 'pending', error = NULL, notification_id = NULL, outgoing_mail_id = NULL, sent_at = NULL, updated_at = now()
       WHERE batch_id = ${params.id}::uuid AND status = 'error' AND recipient IS NOT NULL
       RETURNING user_id
     `;
@@ -667,7 +727,7 @@ export const retryRecipient = async (params: {
   const result = await sql.begin(async (tx) => {
     const updated = await tx<BatchRow[]>`
       UPDATE notifications.batch_recipients
-      SET status = 'pending', error = NULL, notification_id = NULL, sent_at = NULL, updated_at = now()
+      SET status = 'pending', error = NULL, notification_id = NULL, outgoing_mail_id = NULL, sent_at = NULL, updated_at = now()
       WHERE batch_id = ${params.id}::uuid
         AND user_id = ${params.userId}::uuid
         AND status = 'error'