@k2b/cloud 0.26.0 → 0.28.0

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,57 +1,24 @@
-import { createTransport, type Transporter } from "nodemailer";
 import sanitizeHtml from "sanitize-html";
-import { sanitizeEmailHtml } from "../../shared";
+import { sanitizeEmailHtml } from "../../shared/email-html";
 import * as settings from "../settings";
 import { coreSettings } from "../settings/api";
 
-/** Lazily-created transporter — uses current settings on each send. */
-const getTransporter = async (): Promise<Transporter> => {
-  const host = await settings.get<string>("mail.noreply.smtp_host");
-  const port = await settings.get<number>("mail.noreply.smtp_port");
-  const user = await settings.get<string>("mail.noreply.user");
-  const pass = await settings.get<string>("mail.noreply.password");
-
-  return createTransport({
-    host,
-    port,
-    secure: port === 465,
-    auth: { user, pass },
-  });
-};
-
-/** 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 emailFrom = await settings.get<string>("mail.noreply.from");
-
-  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 = await getTransporter();
-
-  await transporter.sendMail({
-    from: `"${appName}" <${emailFrom}>`,
-    to,
-    subject,
-    ...(opts.messageId ? { messageId: opts.messageId } : {}),
-    html,
-    ...(text ? { text } : {}),
-  });
+  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) };
 };
 
 /**

package/src/services/notifications/email-mail.ts

@@ -0,0 +1,101 @@
+import { domainToASCII } from "node:url";
+import type { ZodError } from "zod";
+import { type MailMessage, MailMessageSchema, type MailRecord } from "../../contracts/outgoing-mail";
+import { messageRecord, outgoingMailMessages } from "../outgoing-mail/messages";
+import { sendMail } from "../outgoing-mail/send";
+import { OutgoingMailError } from "../outgoing-mail/store";
+import { prepareNotificationEmail } from "./email-frame";
+
+export const notificationMailError = (error: unknown): Error & { code: string; retryable: boolean } => {
+  const code = error instanceof OutgoingMailError ? error.code : "mail_unavailable";
+  return Object.assign(new Error(error instanceof Error ? error.message : "Outgoing mail is unavailable."), {
+    code,
+    retryable: ["mail_unavailable", "backlog_full", "quota_exceeded", "attachment_storage_full"].includes(code),
+  });
+};
+
+export const normalizeNotificationMail = (to: string, subject: string) => {
+  const separator = to.lastIndexOf("@");
+  const domain = separator < 0 ? "" : to.slice(separator + 1);
+  // URL conversion can discard invalid address characters; leave those for validation.
+  const ascii = domain && !/[^\p{L}\p{N}\p{M}.-]/u.test(domain) ? domainToASCII(domain) : "";
+  return {
+    to: [ascii ? `${to.slice(0, separator + 1)}${ascii}` : to],
+    subject: subject
+      .replace(/[\r\n]+/g, " ")
+      .replace(/\0/g, "")
+      .trim()
+      .slice(0, 998),
+  };
+};
+
+export const notificationMailValidationError = (error: ZodError) =>
+  new OutgoingMailError(
+    "bad_input",
+    `Invalid notification email: ${error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`,
+    400,
+  );
+
+const notificationMailMessage = async (
+  to: string,
+  subject: string,
+  body: { content?: string; rawHtml?: string },
+  key?: string,
+): Promise<MailMessage> => {
+  const parsed = MailMessageSchema.safeParse({
+    ...normalizeNotificationMail(to, subject),
+    ...(await prepareNotificationEmail(body)),
+    ...(key ? { key } : {}),
+  });
+  if (!parsed.success) throw notificationMailValidationError(parsed.error);
+  return parsed.data;
+};
+
+export const sendNotificationMail = async (
+  to: string,
+  subject: string,
+  body: { content?: string; rawHtml?: string },
+  key?: string,
+  signal?: AbortSignal,
+): Promise<MailRecord> => {
+  try {
+    return await sendMail("core", await notificationMailMessage(to, subject, body, key), signal, { trustedHtml: true });
+  } catch (error) {
+    throw notificationMailError(error);
+  }
+};
+
+export const notificationMailOutcome = async (record: MailRecord) => {
+  const row = await outgoingMailMessages.read(record.id, "core").catch(() => undefined);
+  const status = row?.status ?? record.status;
+  const errorCode = row?.error_code ?? (record.error ? "smtp_failed" : null);
+  const errorMessage = row?.error_message ?? row?.smtp_response ?? record.error ?? null;
+  if (status === "sent" || status === "bounced") return { status: "delivered" as const, outgoingMailId: record.id };
+  if (status === "failed" || status === "cancelled") {
+    throw Object.assign(new Error(errorMessage ?? `Outgoing mail ${status}.`), {
+      code: errorCode ?? "smtp_failed",
+      retryable: false,
+      outgoingMailId: record.id,
+    });
+  }
+  const next = row?.next_attempt_at ? new Date(row.next_attempt_at).getTime() - Date.now() : 60_000;
+  // Keep polling within the notification retry interval bounds.
+  const retryAfterMs = Number.isFinite(next) ? Math.min(5 * 60_000, Math.max(2_000, next)) : 60_000;
+  return { status: "pending" as const, outgoingMailId: record.id, retryAfterMs, errorMessage };
+};
+
+export const notificationMailOutcomeById = async (id: string) => {
+  const row = await outgoingMailMessages.read(id, "core").catch((error: unknown) => {
+    throw notificationMailError(error);
+  });
+  if (!row) {
+    // Retention may remove a settled mail before notification recovery. Its
+    // stored identity must never turn that recovery into another SMTP send.
+    throw Object.assign(new Error("Outgoing mail record is no longer available."), {
+      code: "smtp_failed",
+      retryable: false,
+      outgoingMailId: id,
+    });
+  }
+  return notificationMailOutcome(messageRecord(row));
+};

package/src/services/notifications/index.ts

@@ -4,7 +4,7 @@ import type { BoundNotificationDefinition, NotificationRecipientKind, Notificati
 import type { PaginationParams } from "../../contracts/shared";
 import { logger } from "../logging";
 import { escapeLikePattern } from "../postgres";
-import { sendEmail } from "./email";
+import { notificationMailOutcome, sendNotificationMail } from "./email-mail";
 import "./browser";
 import { notificationObservability } from "./observability";
 import { sendTypedNotification, type TypedNotificationSendResult } from "./platform";
@@ -107,6 +107,26 @@ type DbNotificationRow = {
   sent_by_name: string | null;
 };
 
+type LegacyMailRow = { id: string; type: NotificationType; recipient: string; subject: string; content: string; mail_generation: number };
+
+const deliverLegacyMail = async (row: LegacyMailRow, body: { content?: string; rawHtml?: string }) => {
+  const key = `notification-message:${row.id}${row.mail_generation ? `:${row.mail_generation}` : ""}`;
+  try {
+    const record = await sendNotificationMail(row.recipient, row.subject, body, key);
+    await sql`UPDATE notifications.messages SET outgoing_mail_id = ${record.id}::uuid, sent_at = NULL, error = NULL
+      WHERE id = ${row.id}::uuid AND mail_generation = ${row.mail_generation}`;
+    const outcome = await notificationMailOutcome(record);
+    if (outcome.status === "pending") return "pending" as const;
+    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL
+      WHERE id = ${row.id}::uuid AND mail_generation = ${row.mail_generation}`;
+    return "sent" as const;
+  } catch (error) {
+    await sql`UPDATE notifications.messages SET sent_at = NULL, error = ${error instanceof Error ? error.message : String(error)}
+      WHERE id = ${row.id}::uuid AND mail_generation = ${row.mail_generation}`;
+    throw error;
+  }
+};
+
 /**
  * Send a notification. Persists to DB, attempts delivery (if autoSend=true), updates sent_at/error.
  */
@@ -130,15 +150,11 @@ const sendLegacy = async (params: SendNotificationParams): Promise<SendNotificat
 
   // Attempt delivery
   try {
-    if (type === "email") {
-      await sendEmail(recipient, subject, { content, rawHtml });
-    }
-    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}`;
-    return { id, status: "sent" };
+    const status = await deliverLegacyMail({ id, type, recipient, subject, content: dbContent, mail_generation: 0 }, { content, rawHtml });
+    return { id, status };
   } catch (e) {
     const error = e instanceof Error ? e.message : String(e);
     log.error("Failed to send", { type, recipient, error });
-    await sql`UPDATE notifications.messages SET error = ${error} WHERE id = ${id}`;
     return { id, status: "error", error };
   }
 };
@@ -482,23 +498,26 @@ export const getById = async (id: string): Promise<NotificationMessage | null> =
  * Resend a notification (retry delivery).
  */
 export const resend = async (id: string): Promise<{ ok: true } | { ok: false; code: "not_found" | "delivery_failed"; error: string }> => {
-  const notification = await getById(id);
-  if (!notification) {
-    return { ok: false, code: "not_found", error: "Notification not found" };
-  }
-
+  const notification = await sql.begin(async (tx): Promise<(LegacyMailRow & { current_mail_status: string | null }) | undefined> => {
+    const [row] = await tx<(LegacyMailRow & { outgoing_mail_id: string | null; current_mail_status: string | null })[]>`
+      SELECT m.*, mail.status AS current_mail_status FROM notifications.messages m
+      LEFT JOIN outgoing_mail.messages mail ON mail.id = m.outgoing_mail_id
+      WHERE m.id = ${id}::uuid FOR UPDATE OF m
+    `;
+    if (!row || row.current_mail_status === "queued" || row.current_mail_status === "sending" || !row.outgoing_mail_id) return row;
+    const [updated] = await tx<LegacyMailRow[]>`
+      UPDATE notifications.messages SET mail_generation = mail_generation + 1, outgoing_mail_id = NULL, sent_at = NULL, error = NULL
+      WHERE id = ${id}::uuid RETURNING *
+    `;
+    return updated ? { ...updated, current_mail_status: null } : undefined;
+  });
+  if (!notification) return { ok: false, code: "not_found", error: "Notification not found" };
+  if (["queued", "sending"].includes(notification.current_mail_status ?? "")) return { ok: true };
   try {
-    if (notification.type === "email") {
-      await sendEmail(notification.recipient, notification.subject, {
-        rawHtml: notification.content,
-      });
-    }
-    await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}`;
+    await deliverLegacyMail(notification, { rawHtml: notification.content });
     return { ok: true };
   } catch (e) {
-    const error = e instanceof Error ? e.message : String(e);
-    await sql`UPDATE notifications.messages SET error = ${error} WHERE id = ${id}`;
-    return { ok: false, code: "delivery_failed", error };
+    return { ok: false, code: "delivery_failed", error: e instanceof Error ? e.message : String(e) };
   }
 };
 
@@ -535,7 +554,9 @@ export const update = async (
       subject = COALESCE(${data.subject ?? null}, subject),
       content = COALESCE(${data.content ?? null}, content),
       recipient = COALESCE(${data.recipient ?? null}, recipient),
-      error = CASE WHEN ${clearError} THEN NULL ELSE error END
+      error = CASE WHEN ${clearError} THEN NULL ELSE error END,
+      mail_generation = CASE WHEN ${clearError} THEN mail_generation + 1 ELSE mail_generation END,
+      outgoing_mail_id = CASE WHEN ${clearError} THEN NULL ELSE outgoing_mail_id END
     WHERE id = ${id}
   `;
 
@@ -548,7 +569,7 @@ export const update = async (
 export const getPendingSystemCount = async (): Promise<number> => {
   const rows = await sql`
     SELECT COUNT(*)::int as count FROM notifications.messages
-    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL
+    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL AND outgoing_mail_id IS NULL
   `;
   return rows[0]?.count ?? 0;
 };
@@ -563,10 +584,10 @@ export const sendAllPendingSystem = async (): Promise<{
   errors: { id: string; recipient: string; error: string }[];
 }> => {
   // Get all pending system notifications
-  const rows = await sql`
-    SELECT id, type, recipient, subject, content
+  const rows = await sql<LegacyMailRow[]>`
+    SELECT id, type, recipient, subject, content, mail_generation
     FROM notifications.messages
-    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL
+    WHERE sent_at IS NULL AND error IS NULL AND sent_by IS NULL AND outgoing_mail_id IS NULL
     ORDER BY created_at ASC
   `;
 
@@ -575,21 +596,13 @@ export const sendAllPendingSystem = async (): Promise<{
   const errors: { id: string; recipient: string; error: string }[] = [];
 
   for (const row of rows) {
-    const id = row.id as string;
-    const type = row.type as NotificationType;
-    const recipient = row.recipient as string;
-    const subject = row.subject as string;
-    const content = row.content as string;
+    const { id, recipient, content } = row;
 
     try {
-      if (type === "email") {
-        await sendEmail(recipient, subject, { rawHtml: content });
-      }
-      await sql`UPDATE notifications.messages SET sent_at = now(), error = NULL WHERE id = ${id}`;
+      if ((await deliverLegacyMail(row, { rawHtml: content })) === "pending") continue;
       sent++;
     } catch (e) {
       const error = e instanceof Error ? e.message : String(e);
-      await sql`UPDATE notifications.messages SET error = ${error} WHERE id = ${id}`;
       failed++;
       errors.push({ id, recipient, error });
     }

package/src/services/notifications/observability.ts

@@ -1,4 +1,5 @@
 import { type SQL, sql } from "bun";
+import type { MailStatus } from "../../contracts/outgoing-mail";
 import type { NotificationDeliveryStatus } from "../../contracts/user-notifications";
 import { escapeLikePattern, toPgTextArray } from "../postgres";
 
@@ -20,6 +21,8 @@ export type NotificationDeliveryObservabilityItem = {
   required: boolean;
   routePriority: number | null;
   status: NotificationDeliveryStatus;
+  outgoingMailId: string | null;
+  outgoingMailStatus: MailStatus | null;
   attemptCount: number;
   errorCode: string | null;
   errorMessage: string | null;
@@ -79,6 +82,8 @@ type DeliveryRow = {
   required: boolean;
   route_priority: number | null;
   status: NotificationDeliveryStatus;
+  outgoing_mail_id: string | null;
+  outgoing_mail_status: MailStatus | null;
   attempt_count: number;
   error_code: string | null;
   error_message: string | null;
@@ -168,11 +173,12 @@ const listDeliveries = async (input: {
         COALESCE(NULLIF(u.display_name, ''), NULLIF(u.uid, ''), e.recipient_email, e.recipient_key) AS recipient_label,
         COALESCE(NULLIF(u.mail, ''), NULLIF(u.uid, ''), e.recipient_email, e.recipient_key) AS recipient_reference,
         d.channel, d.destination_label, d.required, d.route_priority, d.status,
-        d.attempt_count, d.error_code, d.error_message, d.created_at, d.updated_at, d.delivered_at
+        d.outgoing_mail_id, mail.status AS outgoing_mail_status, d.attempt_count, d.error_code, d.error_message, d.created_at, d.updated_at, d.delivered_at
       FROM notifications.deliveries d
       JOIN notifications.events e ON e.id = d.event_id
       JOIN notifications.definitions n ON n.id = e.definition_id
       LEFT JOIN auth.users u ON u.id = e.recipient_user_id
+      LEFT JOIN outgoing_mail.messages mail ON mail.id = d.outgoing_mail_id
       WHERE ${where}
       ORDER BY d.created_at DESC, d.id DESC
       LIMIT ${perPage} OFFSET ${offset}
@@ -196,6 +202,8 @@ const listDeliveries = async (input: {
       required: row.required,
       routePriority: row.route_priority,
       status: row.status,
+      outgoingMailId: row.outgoing_mail_id,
+      outgoingMailStatus: row.outgoing_mail_status,
       attemptCount: row.attempt_count,
       errorCode: row.error_code,
       errorMessage: row.error_message,

package/src/services/notifications/platform.ts

@@ -407,7 +407,7 @@ export const sendTypedNotification = async <
   if (persisted.prepared) {
     for (const deliveryId of persisted.requiredIds) {
       const result = await processNotificationDelivery(deliveryId);
-      if (result.status === "retry") await enqueueNotificationDelivery(deliveryId, result.retryAfterMs);
+      if (result.status === "retry" || result.status === "pending") await enqueueNotificationDelivery(deliveryId, result.retryAfterMs);
       if (result.activatedIds?.length) await enqueueNotificationDeliveries(result.activatedIds);
     }
     await enqueueNotificationDeliveries(persisted.pendingIds);