@k2b/cloud 0.27.0 → 0.28.0

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

@@ -206,4 +206,14 @@ export { railShortcuts } from "./rail-shortcuts";
 export type { WebVitalsOverview, WebVitalsQuery, WebVitalMetric, WebVitalName } from "./logging/web-vitals";
 
 export { mail } from "./outgoing-mail";
-export type { MailProfile } from "../contracts/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'

package/src/services/notifications/channels.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { EmailNotificationPresentation, NotificationChannelId, NotificationPresentation } from "../../contracts/notification-types";
-import { sendEmail } from "./email";
+import { notificationMailOutcome, notificationMailOutcomeById, sendNotificationMail } from "./email-mail";
 
 export type ResolvedNotificationRecipient = {
   userId: string | null;
@@ -23,7 +23,22 @@ export type NotificationChannelDriver = {
     destination: NotificationDestination;
     event: { id: string; definitionId: string };
   }) => unknown;
-  deliver: (payload: unknown) => Promise<void>;
+  deliver: (
+    payload: unknown,
+    context?: { deliveryId: string; signal?: AbortSignal; outgoingMailId?: string },
+  ) => Promise<
+    | void
+    | {
+        status: "delivered";
+        outgoingMailId?: string;
+      }
+    | {
+        status: "pending";
+        retryAfterMs: number;
+        outgoingMailId?: string;
+        errorMessage?: string | null;
+      }
+  >;
 };
 
 const drivers = new Map<string, NotificationChannelDriver>();
@@ -58,7 +73,6 @@ type EmailPayload = {
   subject: string;
   content?: string;
   rawHtml?: string;
-  messageId?: string;
 };
 
 const parseEmailPayload = (value: unknown): EmailPayload => {
@@ -69,8 +83,7 @@ const parseEmailPayload = (value: unknown): EmailPayload => {
   }
   if (payload.content !== undefined && typeof payload.content !== "string") throw new Error("Invalid email notification payload");
   if (payload.rawHtml !== undefined && typeof payload.rawHtml !== "string") throw new Error("Invalid email notification payload");
-  if (payload.messageId !== undefined && typeof payload.messageId !== "string") throw new Error("Invalid email notification payload");
-  return { to: payload.to, subject: payload.subject, content: payload.content, rawHtml: payload.rawHtml, messageId: payload.messageId };
+  return { to: payload.to, subject: payload.subject, content: payload.content, rawHtml: payload.rawHtml };
 };
 
 const emailDriver: NotificationChannelDriver = {
@@ -80,7 +93,7 @@ const emailDriver: NotificationChannelDriver = {
     const email = normalizeEmail(recipient.email);
     return [{ key: emailKey(email), label: emailLabel(email), context: { email } }];
   },
-  createPayload: ({ presentation, email, destination, event }) => {
+  createPayload: ({ presentation, email, destination }) => {
     const context = destination.context as { email?: unknown };
     if (typeof context.email !== "string") throw new Error("Email destination is missing an address");
     return {
@@ -88,16 +101,23 @@ const emailDriver: NotificationChannelDriver = {
       subject: email?.subject ?? presentation.title,
       content: email?.content ?? presentation.body,
       rawHtml: email?.rawHtml,
-      messageId: `<cloud-notification-${event.id}@cloud.invalid>`,
     } satisfies EmailPayload;
   },
-  deliver: async (value) => {
+  deliver: async (value, context) => {
+    if (context?.outgoingMailId) return notificationMailOutcomeById(context.outgoingMailId);
     const payload = parseEmailPayload(value);
-    await sendEmail(payload.to, payload.subject, {
-      content: payload.content,
-      rawHtml: payload.rawHtml,
-      messageId: payload.messageId,
-    });
+    return notificationMailOutcome(
+      await sendNotificationMail(
+        payload.to,
+        payload.subject,
+        {
+          content: payload.content,
+          rawHtml: payload.rawHtml,
+        },
+        context ? `notification-delivery:${context.deliveryId}` : undefined,
+        context?.signal,
+      ),
+    );
   },
 };
 

package/src/services/notifications/dispatcher.ts

@@ -1,4 +1,5 @@
 import { sql } from "bun";
+import { z } from "zod";
 import { decryptSecret } from "../secrets";
 import { getNotificationChannel } from "./channels";
 
@@ -14,10 +15,12 @@ type DeliveryRow = {
   required: boolean;
   route_priority: number | null;
   attempt_count: number;
+  outgoing_mail_id: string | null;
 };
 
 export type DeliveryAttemptResult =
   | { status: "skipped" | "delivered" | "failed" }
+  | { status: "pending"; retryAfterMs: number }
   | { status: "retry"; retryAfterMs: number; error: string };
 
 const retryDelay = (attempt: number): number => Math.min(BASE_RETRY_MS * 2 ** Math.max(0, attempt - 1), MAX_RETRY_MS);
@@ -65,7 +68,10 @@ const activateNextFallback = async (eventId: string): Promise<string[]> => {
   return rows.map((row) => row.id);
 };
 
-export const processNotificationDelivery = async (deliveryId: string): Promise<DeliveryAttemptResult & { activatedIds?: string[] }> => {
+export const processNotificationDelivery = async (
+  deliveryId: string,
+  signal?: AbortSignal,
+): Promise<DeliveryAttemptResult & { activatedIds?: string[] }> => {
   const rows = await sql<DeliveryRow[]>`
     UPDATE notifications.deliveries
     SET status = 'sending', attempt_count = attempt_count + 1,
@@ -73,7 +79,7 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
     WHERE id = ${deliveryId}::uuid
       AND status = 'pending'
       AND (next_attempt_at IS NULL OR next_attempt_at <= now())
-    RETURNING id, event_id, channel, payload_encrypted, required, route_priority, attempt_count
+    RETURNING id, event_id, channel, payload_encrypted, required, route_priority, attempt_count, outgoing_mail_id
   `;
   const delivery = rows[0];
   if (!delivery) return { status: "skipped" };
@@ -86,10 +92,34 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
       throw Object.assign(new Error("Notification delivery payload is unavailable"), { code: "payload_missing", retryable: false });
     }
     const payload = await decryptSecret(delivery.payload_encrypted);
-    await driver.deliver(payload);
+    const outcome = await driver.deliver(payload, {
+      deliveryId: delivery.id,
+      ...(signal ? { signal } : {}),
+      ...(delivery.outgoing_mail_id ? { outgoingMailId: delivery.outgoing_mail_id } : {}),
+    });
+    // Third-party drivers may return provider bodies; only a UUID can name an outgoing mail.
+    const mailId = z.uuid().safeParse(outcome?.outgoingMailId).data ?? null;
+    if (
+      outcome?.status === "pending" &&
+      typeof outcome.retryAfterMs === "number" &&
+      Number.isFinite(outcome.retryAfterMs) &&
+      outcome.retryAfterMs > 0
+    ) {
+      const retryAfterMs = Math.round(Math.min(MAX_RETRY_MS, Math.max(BASE_RETRY_MS, outcome.retryAfterMs)));
+      await sql`
+        UPDATE notifications.deliveries
+        SET status = 'pending', attempt_count = attempt_count - 1,
+            next_attempt_at = now() + (${retryAfterMs}::int * INTERVAL '1 millisecond'),
+            outgoing_mail_id = COALESCE(${mailId}::uuid, outgoing_mail_id),
+            error_code = NULL, error_message = ${typeof outcome.errorMessage === "string" ? outcome.errorMessage : null}, updated_at = now()
+        WHERE id = ${delivery.id}::uuid
+      `;
+      return { status: "pending", retryAfterMs };
+    }
     await sql`
       UPDATE notifications.deliveries
-      SET status = 'delivered', delivered_at = now(), next_attempt_at = NULL,
+      SET outgoing_mail_id = COALESCE(${mailId}::uuid, outgoing_mail_id),
+          status = 'delivered', delivered_at = now(), next_attempt_at = NULL,
           error_code = NULL, error_message = NULL, payload_encrypted = NULL, updated_at = now()
       WHERE id = ${delivery.id}::uuid
     `;
@@ -98,6 +128,8 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
   } catch (error) {
     const message = error instanceof Error ? error.message : "Notification delivery failed";
     const code = error && typeof error === "object" && "code" in error ? String(error.code) : "provider_error";
+    const outgoingMailId =
+      error && typeof error === "object" && "outgoingMailId" in error ? (z.uuid().safeParse(error.outgoingMailId).data ?? null) : null;
     const retryable = !(error && typeof error === "object" && "retryable" in error && error.retryable === false);
     if (retryable && delivery.attempt_count < MAX_DELIVERY_ATTEMPTS) {
       const retryAfterMs = retryDelay(delivery.attempt_count);
@@ -112,7 +144,8 @@ export const processNotificationDelivery = async (deliveryId: string): Promise<D
 
     await sql`
       UPDATE notifications.deliveries
-      SET status = 'failed', next_attempt_at = NULL, error_code = ${code},
+      SET outgoing_mail_id = COALESCE(${outgoingMailId}::uuid, outgoing_mail_id),
+          status = 'failed', next_attempt_at = NULL, error_code = ${code},
           error_message = ${message}, payload_encrypted = NULL, updated_at = now()
       WHERE id = ${delivery.id}::uuid
     `;
@@ -137,3 +170,22 @@ export const recoverNotificationDeliveries = async (): Promise<string[]> => {
   `;
   return rows.map((row) => row.id);
 };
+
+export const reconcileNotificationMessages = async (): Promise<void> => {
+  await sql`
+    WITH terminal AS (
+      SELECT m.id, m.outgoing_mail_id, mail.status, mail.sent_at,
+        COALESCE(mail.error_message, mail.smtp_response, 'Outgoing mail record is no longer available.') AS error
+      FROM notifications.messages m
+      LEFT JOIN outgoing_mail.messages mail ON mail.id = m.outgoing_mail_id
+      WHERE m.outgoing_mail_id IS NOT NULL AND m.sent_at IS NULL AND m.error IS NULL
+        AND (mail.status IN ('sent', 'bounced', 'failed', 'cancelled') OR mail.id IS NULL)
+      ORDER BY m.outgoing_mail_id, m.id LIMIT 500
+    )
+    UPDATE notifications.messages m
+    SET sent_at = CASE WHEN t.status IN ('sent', 'bounced') THEN t.sent_at ELSE NULL END,
+        error = CASE WHEN t.status IN ('sent', 'bounced') THEN NULL ELSE t.error END
+    FROM terminal t
+    WHERE m.id = t.id AND m.outgoing_mail_id = t.outgoing_mail_id AND m.sent_at IS NULL AND m.error IS NULL
+  `;
+};

package/src/services/notifications/email-frame.fixture.html

@@ -0,0 +1,51 @@
+
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body style="margin:0;padding:0;background:#f4f4f5;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="padding:32px 16px;">
+    <tr><td align="center">
+      <table width="100%" style="max-width:520px;" cellpadding="0" cellspacing="0">
+
+        <!-- Header -->
+        <tr><td style="background:#ffffff;padding:20px 24px;border-radius:12px 12px 0 0;border:1px solid #e4e4e7;border-bottom:none;">
+          <table cellpadding="0" cellspacing="0"><tr>
+          <td style="padding-right:12px;vertical-align:middle;">
+              <img src="https://example.test/logo.svg" alt="Logo" width="28" height="28" style="display:block;">
+            </td>
+            <td style="vertical-align:middle;">
+              <span style="font-size:16px;font-weight:600;color:#18181b;">Test Cloud</span>
+            </td>
+          </tr></table>
+        </td></tr>
+
+        <!-- Content -->
+        <tr><td style="background:#ffffff;padding:28px 24px;border-left:1px solid #e4e4e7;border-right:1px solid #e4e4e7;">
+          <div style="font-size:14px;line-height:1.6;color:#27272a;">
+            {{body}}
+          </div>
+        </td></tr>
+
+        <!-- Footer -->
+        <tr><td style="background:#fafafa;padding:16px 24px;border-radius:0 0 12px 12px;border:1px solid #e4e4e7;border-top:none;">
+          <p style="margin:0 0 8px;font-size:11px;color:#71717a;text-align:center;">
+            <a href="https://example.test/impressum" style="color:#71717a;text-decoration:underline;">Imprint</a>
+            &nbsp;&middot;&nbsp;
+            <a href="https://example.test/legal/terms" style="color:#71717a;text-decoration:underline;">Terms</a>
+            &nbsp;&middot;&nbsp;
+            <a href="https://example.test/legal/privacy" style="color:#71717a;text-decoration:underline;">Privacy</a>
+          </p>
+          <p style="margin:0;font-size:11px;color:#a1a1aa;text-align:center;">
+            This message was sent automatically. Please do not reply to this email.
+          </p>
+        </td></tr>
+
+      </table>
+    </td></tr>
+  </table>
+</body>
+<!-- the answer is 42 ;D -->
+</html>

package/src/services/notifications/{email.ts → email-frame.ts}

@@ -1,47 +1,24 @@
 import sanitizeHtml from "sanitize-html";
-import { sanitizeEmailHtml } from "../../shared";
-import { resolveMailCredentials } from "../outgoing-mail/store";
-import { buildMailTransport } from "../outgoing-mail/transport";
+import { sanitizeEmailHtml } from "../../shared/email-html";
 import * as settings from "../settings";
 import { coreSettings } from "../settings/api";
 
-/** Sanitize plain text content (no HTML allowed). */
 const sanitizeContent = (content: string): string => sanitizeHtml(content, { allowedTags: [], allowedAttributes: {} });
 
-/** Send an email with the standard HTML template. */
-export const sendEmail = async (
-  to: string,
-  subject: string,
-  opts: { content?: string; rawHtml?: string; messageId?: string },
-): Promise<void> => {
+// sanitize-html decodes entities before escaping &, < and > again. Decode only
+// those escapes once, so literal entity text is not recursively interpreted.
+const htmlText = (html: string): string =>
+  sanitizeContent(html.replace(/<br\b[^>]*>|<\/(?:p|div|h[1-6]|li|tr|td|th|ul|ol|table)>/gi, " "))
+    .replace(/&(amp|lt|gt);/g, (entity) => (entity === "&amp;" ? "&" : entity === "&lt;" ? "<" : ">"))
+    .replace(/\s+/g, " ")
+    .trim();
+
+export const prepareNotificationEmail = async (opts: { content?: string; rawHtml?: string }): Promise<{ html: string; text: string }> => {
   const rawAppUrl = await settings.get<string>("app.url");
   const appUrl = rawAppUrl.startsWith("http") ? rawAppUrl : `https://${rawAppUrl}`;
   const appName = await settings.get<string>("app.name");
-  const profile = await resolveMailCredentials();
-
-  let body = "";
-  if (opts.rawHtml) {
-    body = sanitizeEmailHtml(opts.rawHtml);
-  } else if (opts.content) {
-    body = `<p>${sanitizeContent(opts.content)}</p>`;
-  }
-  const text = opts.content ? sanitizeContent(opts.content) : undefined;
-
-  const html = await buildHtml(appUrl, appName, body);
-  const transporter = buildMailTransport(profile);
-
-  try {
-    await transporter.sendMail({
-      from: { address: profile.fromAddress, name: profile.fromName ?? appName },
-      to,
-      subject,
-      ...(opts.messageId ? { messageId: opts.messageId } : {}),
-      html,
-      ...(text ? { text } : {}),
-    });
-  } finally {
-    transporter.close();
-  }
+  const body = opts.rawHtml ? sanitizeEmailHtml(opts.rawHtml) : opts.content ? `<p>${sanitizeContent(opts.content)}</p>` : "";
+  return { html: await buildHtml(appUrl, appName, body), text: opts.content ? sanitizeContent(opts.content) : htmlText(body) };
 };
 
 /**