@k2b/cloud 0.27.0 → 0.28.0

package/src/services/outgoing-mail/dispatcher.ts

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { Socket } from "node:net";
+import { Readable } from "node:stream";
+import { sql } from "bun";
+import { z } from "zod";
+import { listApps } from "../../_internal/registry";
+import { parsePgJsonValue } from "../postgres";
+import { get } from "../settings";
+import { deleteMailObjects, verifyMailAttachment } from "./attachments";
+import { mailBackoffMs, mailEnvelope } from "./message";
+import { allowedMailProfile, type MessageRow, messageAttachmentRefs, messageRecord, outgoingMailMessages } from "./messages";
+import { OutgoingMailError, resolveMailCredentials } from "./store";
+import { mailAttachments, mailSettled } from "./sync";
+import { smtpFailureMessage } from "./test-send";
+import { buildMailTransport } from "./transport";
+
+export const cleanupMailAttachments = async (id: string): Promise<void> => {
+  const row = await outgoingMailMessages.read(id);
+  if (!row || ["queued", "sending"].includes(row.status)) return;
+  await deleteMailObjects(messageAttachmentRefs(row));
+  await sql`UPDATE outgoing_mail.messages SET attachment_refs = NULL WHERE id = ${id}::uuid AND status NOT IN ('queued','sending')`;
+};
+export const publishMailSettled = async (id: string): Promise<void> => {
+  await mailSettled().publish({ tenantId: id, data: id });
+};
+const smtpResponseRetryable = (error: unknown): boolean => {
+  const responseCode = error && typeof error === "object" && "responseCode" in error ? Number(error.responseCode) : undefined;
+  return responseCode === undefined || !Number.isFinite(responseCode) || responseCode < 500;
+};
+export const smtpRetryable = (error: unknown): boolean => {
+  if (error && typeof error === "object" && "rejectedErrors" in error && Array.isArray(error.rejectedErrors) && error.rejectedErrors.length)
+    return error.rejectedErrors.some(smtpResponseRetryable);
+  return smtpResponseRetryable(error);
+};
+const rejectReason = (error: unknown, fallback: string): string =>
+  error && typeof error === "object" && "response" in error && typeof error.response === "string" ? error.response : fallback;
+const cancelled = async (row: MessageRow, code: "profile_removed" | "profile_not_allowed", message?: string) => {
+  await sql`UPDATE outgoing_mail.messages SET status = 'cancelled', error_code = ${code}, error_message = ${message ?? (code === "profile_removed" ? "Outgoing mail profile was removed." : "Outgoing mail profile access was revoked.")},
+    next_attempt_at = NULL, updated_at = now() WHERE id = ${row.id}::uuid AND status = 'sending' AND attempt_count = ${row.attempt_count}`;
+};
+export const processOutgoingMail = async (id: string, signal?: AbortSignal): Promise<void> => {
+  const [row] = await sql<
+    MessageRow[]
+  >`UPDATE outgoing_mail.messages SET status = 'sending', attempt_count = attempt_count + 1, updated_at = now()
+    WHERE id = ${id}::uuid AND status = 'queued' AND lane = 'immediate' AND (next_attempt_at IS NULL OR next_attempt_at <= now() OR deadline_at <= now())
+    RETURNING *, created_at::text AS cursor_created_at`;
+  if (!row) return;
+  await attemptOutgoingMail(row, signal);
+};
+
+/** Both lanes share policy, attachments, SMTP outcomes and retry handling. */
+export const attemptOutgoingMail = async (row: MessageRow, signal?: AbortSignal): Promise<void> => {
+  const id = row.id;
+  let credentials: Awaited<ReturnType<typeof resolveMailCredentials>> | undefined;
+  try {
+    if (new Date(row.deadline_at).getTime() <= Date.now()) {
+      await sql`UPDATE outgoing_mail.messages SET status = 'failed', error_code = COALESCE(error_code, 'smtp_failed'), error_message = COALESCE(error_message, 'Outgoing mail delivery deadline expired.'), next_attempt_at = NULL, updated_at = now() WHERE id = ${id}::uuid AND status = 'sending' AND attempt_count = ${row.attempt_count}`;
+      return;
+    }
+    if (!row.profile_id) {
+      await cancelled(row, "profile_removed");
+      return;
+    }
+    const apps = await listApps();
+    const app = apps.find((app) => app.id === row.app_id);
+    if (app && !app.platformPermissions?.includes("mail:send")) {
+      await cancelled(row, "profile_not_allowed", "The application no longer declares mail:send.");
+      return;
+    }
+    // Core mail speaks for the installation, as system email did before it used outgoing mail.
+    const senderName = row.app_id === "core" ? await get<string>("app.name") : app?.name || row.app_id;
+    try {
+      await sql.begin(async (tx) => {
+        await tx`SELECT pg_advisory_xact_lock_shared(hashtextextended('outgoing_mail.policy', 0))`;
+        const profile = await allowedMailProfile(tx, row.app_id, row.profile_key);
+        if (profile.id !== row.profile_id) throw new OutgoingMailError("profile_removed", "Outgoing mail profile was replaced.");
+      });
+    } catch (error) {
+      if (
+        error instanceof OutgoingMailError &&
+        ["profile_unknown", "profile_removed", "mail_unavailable", "profile_not_allowed", "profile_required"].includes(error.code)
+      ) {
+        await cancelled(
+          row,
+          ["profile_unknown", "profile_removed", "mail_unavailable"].includes(error.code) ? "profile_removed" : "profile_not_allowed",
+        );
+        return;
+      }
+      throw error;
+    }
+    const refs = messageAttachmentRefs(row);
+    const metadata = messageRecord(row).attachments;
+    if (refs.length !== metadata.length) throw new OutgoingMailError("attachment_lost", "An outgoing mail attachment is missing.");
+    const attempt = new AbortController();
+    const abort = () => attempt.abort();
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) abort();
+    const timer = setTimeout(abort, 60_000);
+    const streams: Readable[] = [];
+    try {
+      for (const [index, ref] of refs.entries()) await verifyMailAttachment(ref, metadata[index]!, attempt.signal);
+      const attachments = [];
+      for (const [index, ref] of refs.entries()) {
+        const stored = await mailAttachments().get(ref, { signal: attempt.signal });
+        if (!stored) throw new OutgoingMailError("attachment_lost", "An outgoing mail attachment is missing.");
+        const item = metadata[index]!;
+        const stream = Readable.from(
+          (async function* () {
+            const reader = stored.body.getReader();
+            const hash = createHash("sha256");
+            let bytes = 0;
+            try {
+              while (true) {
+                const chunk = await reader.read();
+                if (chunk.done) break;
+                bytes += chunk.value.byteLength;
+                if (bytes > item.size) throw new OutgoingMailError("attachment_lost", "Attachment size changed.");
+                hash.update(chunk.value);
+                yield chunk.value;
+              }
+              if (bytes !== item.size || hash.digest("hex") !== item.sha256)
+                throw new OutgoingMailError("attachment_lost", "Attachment checksum changed.");
+            } finally {
+              await reader.cancel().catch(() => {});
+              reader.releaseLock();
+            }
+          })(),
+        );
+        streams.push(stream);
+        attachments.push({ filename: item.filename, contentType: item.contentType, content: stream });
+      }
+      // Load the checked profile by ID: a profile deleted (or recreated under its key) since the check is profile_removed.
+      credentials = await resolveMailCredentials({ id: row.profile_id });
+      const socket = new Socket();
+      // DNS can complete after cancellation; tear down a late connection too.
+      socket.once("connect", () => {
+        if (attempt.signal.aborted) socket.destroy();
+      });
+      const transport = buildMailTransport(credentials, socket);
+      const stop = () => {
+        socket.destroy();
+        transport.close();
+        for (const stream of streams) stream.destroy();
+      };
+      attempt.signal.addEventListener("abort", stop, { once: true });
+      try {
+        if (attempt.signal.aborted) throw new Error("SMTP attempt cancelled");
+        const result = await transport.sendMail({
+          ...mailEnvelope(credentials, senderName, row.from_name),
+          envelope: { from: credentials.fromAddress, to: row.to_addresses },
+          to: row.to_addresses,
+          subject: row.subject,
+          text: row.text_body ?? "",
+          html: row.html_body ?? undefined,
+          replyTo: row.reply_to ?? undefined,
+          messageId: row.message_id_header,
+          headers: row.headers === null ? undefined : z.record(z.string(), z.string()).parse(parsePgJsonValue(row.headers)),
+          attachments,
+          disableFileAccess: true,
+          disableUrlAccess: true,
+        });
+        const failures = (result.rejected ?? []).map((recipient: string, index: number) => ({
+          recipient,
+          reason: rejectReason(result.rejectedErrors?.[index], "Recipient rejected."),
+          at: new Date().toISOString(),
+        }));
+        await sql`UPDATE outgoing_mail.messages SET status = 'sent', sent_at = now(), next_attempt_at = NULL, error_code = NULL, error_message = NULL,
+          smtp_response = ${result.response}, failures = ${JSON.stringify(failures)}::text::jsonb, updated_at = now()
+          WHERE id = ${id}::uuid AND status = 'sending' AND attempt_count = ${row.attempt_count}`;
+      } finally {
+        attempt.signal.removeEventListener("abort", stop);
+        socket.destroy();
+        transport.close();
+      }
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      attempt.abort();
+      for (const stream of streams) stream.destroy();
+    }
+  } catch (error) {
+    if (error instanceof OutgoingMailError && ["profile_unknown", "profile_removed"].includes(error.code)) {
+      await cancelled(row, "profile_removed");
+      return;
+    }
+    const secrets = credentials
+      ? [
+          credentials.smtpUser,
+          credentials.smtpPassword,
+          credentials.smtpUser ? `\0${credentials.smtpUser}\0${credentials.smtpPassword ?? ""}` : null,
+        ]
+      : [];
+    const message =
+      credentials || error instanceof OutgoingMailError
+        ? smtpFailureMessage(error, secrets)
+        : "Outgoing mail delivery is temporarily unavailable.";
+    const lost = error instanceof OutgoingMailError && error.code === "attachment_lost";
+    const retry = !lost && smtpRetryable(error) && new Date(row.deadline_at).getTime() > Date.now();
+    const next = new Date(Date.now() + mailBackoffMs(row.attempt_count));
+    await sql`UPDATE outgoing_mail.messages SET status = ${retry ? "queued" : "failed"}, error_code = ${lost ? "attachment_lost" : "smtp_failed"}, error_message = ${message},
+      next_attempt_at = ${retry ? next : null}, updated_at = now() WHERE id = ${id}::uuid AND status = 'sending' AND attempt_count = ${row.attempt_count}`;
+  } finally {
+    // Cleanup failure must never turn SMTP success into another delivery attempt.
+    await cleanupMailAttachments(id).catch(() => {});
+    await publishMailSettled(id).catch(() => {});
+  }
+};
+export const recoverOutgoingMail = async (): Promise<string[]> => {
+  await sql`WITH stale AS (SELECT id FROM outgoing_mail.messages WHERE status = 'sending' AND updated_at < now() - INTERVAL '5 minutes' LIMIT 1000 FOR UPDATE SKIP LOCKED)
+    UPDATE outgoing_mail.messages SET status = 'queued', next_attempt_at = now(), updated_at = now() WHERE id IN (SELECT id FROM stale)`;
+  const orphaned = await sql<{ id: string }[]>`WITH orphaned AS (
+    SELECT id FROM outgoing_mail.messages WHERE status = 'queued' AND lane = 'bulk' AND profile_id IS NULL
+    LIMIT 1000 FOR UPDATE SKIP LOCKED
+  ) UPDATE outgoing_mail.messages SET status = 'cancelled', error_code = 'profile_removed',
+    error_message = 'Outgoing mail profile was removed.', next_attempt_at = NULL, updated_at = now()
+    WHERE id IN (SELECT id FROM orphaned) RETURNING id`;
+  const expired = await sql<{ id: string }[]>`WITH expired AS (
+    SELECT id FROM outgoing_mail.messages WHERE status = 'queued' AND lane = 'bulk' AND deadline_at <= now()
+    LIMIT 1000 FOR UPDATE SKIP LOCKED
+  ) UPDATE outgoing_mail.messages SET status = 'failed', error_code = COALESCE(error_code, 'smtp_failed'),
+    error_message = COALESCE(error_message, 'Outgoing mail delivery deadline expired.'), next_attempt_at = NULL, updated_at = now()
+    WHERE id IN (SELECT id FROM expired) RETURNING id`;
+  for (const row of [...orphaned, ...expired]) await publishMailSettled(row.id).catch(() => {});
+  const cleanup = await sql<
+    { id: string }[]
+  >`SELECT id FROM outgoing_mail.messages WHERE status NOT IN ('queued','sending') AND attachment_refs IS NOT NULL LIMIT 1000`;
+  for (const row of cleanup) await cleanupMailAttachments(row.id).catch(() => {});
+  const due = await sql<{ id: string }[]>`SELECT id FROM outgoing_mail.messages WHERE lane = 'immediate' AND status = 'queued'
+    AND (next_attempt_at IS NULL OR next_attempt_at <= now() OR deadline_at <= now()) ORDER BY next_attempt_at NULLS FIRST, created_at LIMIT 1000`;
+  return due.map((row) => row.id);
+};

package/src/services/outgoing-mail/drain.ts

@@ -0,0 +1,60 @@
+import { sql } from "bun";
+import { mailNextDrainDelay } from "./bulk";
+import { attemptOutgoingMail } from "./dispatcher";
+import type { MessageRow } from "./messages";
+
+export const MAIL_DRAIN_MS = 60_000;
+export const claimOutgoingBulkMail = async (
+  profileId: string,
+): Promise<{ row: MessageRow; slotAt: string; grantedAt: string } | undefined> =>
+  sql.begin(async (tx) => {
+    // Wait for acceptance's share lock before reading the clock and reserving a slot.
+    await tx`SELECT 1 FROM outgoing_mail.profiles WHERE id = ${profileId}::uuid FOR NO KEY UPDATE`;
+    const [slot] = await tx<{ slot_at: string; granted_at: string }[]>`UPDATE outgoing_mail.profiles p
+      SET next_bulk_slot_at = greatest(p.next_bulk_slot_at, c.at) + (60000.0 / p.pace_per_minute) * INTERVAL '1 millisecond'
+      FROM (SELECT clock_timestamp() AS at) c WHERE p.id = ${profileId}::uuid AND p.next_bulk_slot_at <= c.at
+      RETURNING p.next_bulk_slot_at::text AS slot_at, c.at::text AS granted_at`;
+    if (!slot) return undefined;
+    const [row] = await tx<MessageRow[]>`WITH due AS (
+      SELECT id FROM outgoing_mail.messages WHERE profile_id = ${profileId}::uuid AND status = 'queued' AND lane = 'bulk'
+      AND (next_attempt_at IS NULL OR next_attempt_at <= now()) AND deadline_at > now()
+      ORDER BY COALESCE(next_attempt_at, created_at), id LIMIT 1 FOR UPDATE SKIP LOCKED
+    ) UPDATE outgoing_mail.messages SET status = 'sending', attempt_count = attempt_count + 1, updated_at = now()
+      WHERE id IN (SELECT id FROM due) RETURNING *, created_at::text AS cursor_created_at`;
+    // An idle claim consumes at most one slot. No refund race or extra state is needed.
+    return row ? { row, slotAt: slot.slot_at, grantedAt: slot.granted_at } : undefined;
+  });
+export const nextOutgoingBulkDelay = async (profileId: string): Promise<number | undefined> => {
+  const [next] = await sql<{ slot: Date; due: Date; current: Date }[]>`SELECT p.next_bulk_slot_at AS slot, now() AS current, m.due
+    FROM outgoing_mail.profiles p CROSS JOIN LATERAL (
+      SELECT COALESCE(next_attempt_at, created_at) AS due FROM outgoing_mail.messages
+      WHERE profile_id = p.id AND lane = 'bulk' AND status = 'queued' AND deadline_at > now()
+      ORDER BY COALESCE(next_attempt_at, created_at), id LIMIT 1
+    ) m WHERE p.id = ${profileId}::uuid`;
+  return next
+    ? mailNextDrainDelay(new Date(next.current).getTime(), new Date(next.slot).getTime(), new Date(next.due).getTime())
+    : undefined;
+};
+export const dueOutgoingBulkProfiles = async (): Promise<string[]> => {
+  const rows = await sql<{ id: string }[]>`SELECT p.id FROM outgoing_mail.profiles p WHERE EXISTS (
+    SELECT 1 FROM outgoing_mail.messages m WHERE m.profile_id = p.id AND m.lane = 'bulk' AND m.status = 'queued'
+    AND COALESCE(m.next_attempt_at, m.created_at) <= now() AND m.deadline_at > now()
+  ) LIMIT 1000`;
+  return rows.map((row) => row.id);
+};
+/** Stop at the next closed gate and continue durably instead of occupying a worker while waiting. */
+export const drainOutgoingMail = async (
+  profileId: string,
+  signal?: AbortSignal,
+  heartbeat?: () => Promise<void>,
+): Promise<number | undefined> => {
+  const until = Date.now() + MAIL_DRAIN_MS;
+  // The run window bounds claims; only shutdown may cancel the current attempt.
+  while (!signal?.aborted && Date.now() < until) {
+    const claimed = await claimOutgoingBulkMail(profileId);
+    if (!claimed) break;
+    await attemptOutgoingMail(claimed.row, signal);
+    await heartbeat?.();
+  }
+  return nextOutgoingBulkDelay(profileId);
+};

package/src/services/outgoing-mail/enqueue.ts

@@ -0,0 +1,180 @@
+import { type SQL, sql } from "bun";
+import type { MailMessage } from "../../contracts/outgoing-mail";
+import {
+  cancelMailStreams,
+  deleteMailObjects,
+  MAIL_ATTACHMENT_UPLOAD_MS,
+  type UploadedAttachments,
+  uploadMailAttachments,
+} from "./attachments";
+import { mailBacklogFull, mailBatchId } from "./bulk";
+import {
+  type AcceptedProfile,
+  allowedMailProfile,
+  insertMailMessage,
+  type MailAcceptanceOptions,
+  MailQuotaError,
+  type MessageRow,
+  mailQuotaUsed,
+  outgoingMailMessages,
+  recordMailBatch,
+} from "./messages";
+import { OutgoingMailError } from "./store";
+import { mailAttachments, mailDrainJob, mailSettled, submitMailDrain } from "./sync";
+
+type BatchItem = { id: string; message: MailMessage; existing?: MessageRow; uploaded: UploadedAttachments };
+type AcceptedBatch = { batchId: string; rows: MessageRow[]; created: MessageRow[] };
+const lockBatchApp = async (db: SQL, appId: string) => {
+  // One app lock serializes batches with batches and keyed sends without per-key locks.
+  // Lock order: policy -> app -> key (send only) -> quota -> backlog -> call.
+  await db`SELECT pg_advisory_xact_lock_shared(hashtextextended('outgoing_mail.policy', 0))`;
+  await db`SELECT pg_advisory_xact_lock(hashtextextended(${appId}, 5))`;
+};
+/** Retain uploads when a lost COMMIT response cannot be resolved by a recovery read. */
+export class MailAcceptanceUnknown extends OutgoingMailError {
+  constructor() {
+    super("mail_unavailable", "Outgoing mail acceptance could not be determined. Retry with the same keys.", 502);
+  }
+}
+const checkBatch = async (db: SQL, appId: string, items: readonly BatchItem[]) => {
+  const profiles = new Map<string, AcceptedProfile>();
+  // Stable order for batches that request multiple profiles.
+  for (const key of [...new Set(items.map((item) => item.message.profile))].sort())
+    profiles.set(key ?? "", await allowedMailProfile(db, appId, key));
+  const totals = new Map<string, { profile: AcceptedProfile; recipients: number; count: number }>();
+  for (const item of items) {
+    const profile = profiles.get(item.message.profile ?? "")!;
+    if (item.uploaded.metadata.reduce((sum, attachment) => sum + attachment.size, 0) > profile.max_attachment_bytes)
+      throw new OutgoingMailError("attachments_too_large", "Attachments exceed the profile's total byte limit.");
+    const total = totals.get(profile.id) ?? { profile, recipients: 0, count: 0 };
+    total.recipients += item.message.to.length;
+    total.count++;
+    totals.set(profile.id, total);
+  }
+  for (const id of [...totals.keys()].sort()) {
+    const { profile, recipients, count } = totals.get(id)!;
+    // Same quota lock as immediate acceptance, plus a profile-wide backlog lock across apps.
+    await db`SELECT pg_advisory_xact_lock(hashtextextended(${JSON.stringify([appId, id])}, 2))`;
+    await db`SELECT pg_advisory_xact_lock(hashtextextended(${id}, 3))`;
+    const used = await mailQuotaUsed(db, appId, id);
+    if (profile.daily_recipient_limit !== null && used + recipients > profile.daily_recipient_limit)
+      throw new MailQuotaError(profile.daily_recipient_limit, used, recipients);
+    const [backlog] = await db<{ queued: number }[]>`SELECT count(*)::int AS queued FROM outgoing_mail.messages
+      WHERE profile_id = ${id}::uuid AND lane = 'bulk' AND status = 'queued'`;
+    if (mailBacklogFull(backlog?.queued ?? 0, count, profile.pace_per_minute))
+      throw new OutgoingMailError("backlog_full", "The profile's bulk queue exceeds 24 hours of delivery capacity.", 409);
+  }
+  return profiles;
+};
+export const outgoingMailBatches = {
+  async accept(appId: string, proposed: string, items: readonly BatchItem[], options?: MailAcceptanceOptions): Promise<AcceptedBatch> {
+    let result: AcceptedBatch | undefined;
+    try {
+      return await sql.begin(async (tx) => {
+        await lockBatchApp(tx, appId);
+        const known: (MessageRow | undefined)[] = [];
+        for (const item of items) known.push(await outgoingMailMessages.known(appId, item.message.key, tx));
+        const fresh = items.filter((_, index) => !known[index]);
+        if (fresh.some((item) => item.existing))
+          throw new OutgoingMailError(
+            "mail_unavailable",
+            "An idempotent mail record expired during acceptance. Retry with fresh attachments.",
+          );
+        const profiles = await checkBatch(tx, appId, fresh);
+        await tx`SELECT pg_advisory_xact_lock(hashtextextended(${proposed}, 4))`;
+        let batchId = mailBatchId(proposed, known);
+        const rows: MessageRow[] = [];
+        const created: MessageRow[] = [];
+        for (const [index, item] of items.entries()) {
+          let row = known[index];
+          if (!row) {
+            row = await insertMailMessage(
+              tx,
+              appId,
+              item.id,
+              item.message,
+              item.uploaded,
+              profiles.get(item.message.profile ?? "")!,
+              batchId,
+              options,
+            );
+            if (row) created.push(row);
+            else row = await outgoingMailMessages.known(appId, item.message.key, tx);
+          }
+          if (!row) throw new Error("Outgoing mail batch insert returned no row");
+          rows.push(row);
+        }
+        if (!created.length) batchId = mailBatchId(proposed, rows);
+        await recordMailBatch(
+          appId,
+          items.map((item) => item.message),
+          rows,
+          batchId,
+          tx,
+        );
+        result = { batchId, rows, created };
+        return result;
+      });
+    } catch (error) {
+      if (result?.created.length) {
+        // A callback completed but COMMIT may have lost its response. The call lock
+        // waits for that transaction to finish before deciding whether it recorded rows.
+        try {
+          const committed = await sql.begin(async (tx) => {
+            await tx`SELECT pg_advisory_xact_lock(hashtextextended(${proposed}, 4))`;
+            return !!(await outgoingMailMessages.read(result!.created[0]!.id, appId, tx));
+          });
+          if (committed) return result;
+        } catch {
+          throw new MailAcceptanceUnknown();
+        }
+      }
+      throw error;
+    }
+  },
+};
+export const enqueueMail = async (
+  appId: string,
+  messages: readonly MailMessage[],
+  options?: MailAcceptanceOptions,
+): Promise<{ batchId: string; ids: string[] }> => {
+  const items: BatchItem[] = [];
+  try {
+    for (const message of messages) {
+      items.push({ id: crypto.randomUUID(), message, uploaded: { metadata: [], refs: [] } });
+    }
+    const profiles = await sql.begin(async (tx) => {
+      await lockBatchApp(tx, appId);
+      for (const item of items) {
+        item.existing = await outgoingMailMessages.known(appId, item.message.key, tx);
+        if (item.existing) cancelMailStreams(item.message.attachments);
+      }
+      return checkBatch(
+        tx,
+        appId,
+        items.filter((item) => !item.existing),
+      );
+    });
+    const fresh = items.filter((item) => !item.existing);
+    if (fresh.length) await Promise.all([mailDrainJob().ready(), mailSettled().ready(), mailAttachments().ready()]);
+    const deadline = Date.now() + MAIL_ATTACHMENT_UPLOAD_MS;
+    for (const item of fresh)
+      item.uploaded = await uploadMailAttachments(
+        item.id,
+        item.message.attachments ?? [],
+        profiles.get(item.message.profile ?? "")!.max_attachment_bytes,
+        deadline,
+      );
+    const accepted = await outgoingMailBatches.accept(appId, crypto.randomUUID(), items, options);
+    const createdIds = new Set(accepted.created.map((row) => row.id));
+    for (const item of items) if (!createdIds.has(item.id)) await deleteMailObjects(item.uploaded.refs).catch(() => {});
+    for (const id of new Set(accepted.created.flatMap((row) => (row.profile_id ? [row.profile_id] : []))))
+      void submitMailDrain(id).catch(() => {});
+    return { batchId: accepted.batchId, ids: accepted.rows.map((row) => row.id) };
+  } catch (error) {
+    for (const message of messages) cancelMailStreams(message.attachments);
+    // Only an indeterminate COMMIT retains objects for the 48-hour expiry.
+    if (!(error instanceof MailAcceptanceUnknown)) for (const item of items) await deleteMailObjects(item.uploaded.refs).catch(() => {});
+    throw error;
+  }
+};

package/src/services/outgoing-mail/index.ts

@@ -1,19 +1,112 @@
 import { fail, ok, type Result } from "@k2b/stdlib";
 import { getProcessApplicationId, getProcessPlatformPermissions } from "../../_internal/process-identity";
-import type { MailProfile } from "../../contracts/outgoing-mail";
-import { outgoingMailStore } from "./store";
+import {
+  MailBatchSchema,
+  type MailFilter,
+  MailFilterSchema,
+  type MailMessage,
+  MailMessageSchema,
+  type MailPage,
+  type MailPageParams,
+  MailPageParamsSchema,
+  type MailProfile,
+  type MailRecord,
+  type MailServiceError,
+} from "../../contracts/outgoing-mail";
+import { cancelMailStreams } from "./attachments";
+import { enqueueMail } from "./enqueue";
+import { outgoingMailMessages, recordMailBatch, recordMailSend } from "./messages";
+import { sendMail } from "./send";
+import { OutgoingMailError, outgoingMailStore } from "./store";
 
+const identity = (): Result<string, MailServiceError> => {
+  const appId = getProcessApplicationId();
+  if (!appId) return fail({ code: "mail_unavailable", message: "Start the application before using outgoing mail.", status: 500 });
+  if (!getProcessPlatformPermissions().includes("mail:send"))
+    return fail({ code: "mail_not_declared", message: 'Declare platformPermissions: ["mail:send"].', status: 403 });
+  return ok(appId);
+};
+const failure = (error: unknown): MailServiceError => {
+  if (!(error instanceof OutgoingMailError))
+    return { code: "mail_unavailable", message: "Outgoing mail storage is unavailable.", status: 500 };
+  return {
+    code: error.code,
+    message: error.message,
+    status: error.code === "mail_unavailable" || error.status === 502 ? 500 : error.status,
+    ...("limit" in error && typeof error.limit === "number" ? { limit: error.limit } : {}),
+    ...("used" in error && typeof error.used === "number" ? { used: error.used } : {}),
+    ...("requested" in error && typeof error.requested === "number" ? { requested: error.requested } : {}),
+  };
+};
 export const mail = {
-  async profiles(): Promise<Result<MailProfile[]>> {
-    const appId = getProcessApplicationId();
-    if (!appId)
-      return fail({ code: "mail_unavailable", message: "Start the application before reading outgoing mail profiles.", status: 500 });
-    if (!getProcessPlatformPermissions().includes("mail:send"))
-      return fail({ code: "mail_not_declared", message: 'Declare platformPermissions: ["mail:send"].', status: 403 });
+  async enqueue(messages: MailMessage[]): Promise<Result<{ batchId: string; ids: string[] }, MailServiceError>> {
+    const caller = identity();
+    const parsed = caller.ok ? MailBatchSchema.safeParse(messages) : undefined;
+    const cancel = () => {
+      if (Array.isArray(messages)) for (const message of messages) cancelMailStreams(message?.attachments);
+    };
+    if (!caller.ok || !parsed?.success) {
+      cancel();
+      const appId = getProcessApplicationId();
+      const issue: MailServiceError = caller.ok
+        ? { code: "bad_input", message: "Provide 1–1000 valid messages with distinct keys.", status: 400 }
+        : caller.error;
+      if (appId)
+        await recordMailBatch(appId, Array.isArray(messages) ? messages : [], [], undefined, undefined, issue.code).catch(() => {});
+      return fail(issue);
+    }
     try {
-      return ok(await outgoingMailStore.profilesForApp(appId));
+      return ok(await enqueueMail(caller.data, parsed.data));
+    } catch (error) {
+      cancel();
+      const issue = failure(error);
+      await recordMailBatch(caller.data, parsed.data, [], undefined, undefined, issue.code).catch(() => {});
+      return fail(issue);
+    }
+  },
+  async profiles(): Promise<Result<MailProfile[], MailServiceError>> {
+    const caller = identity();
+    if (!caller.ok) return caller;
+    try {
+      return ok(await outgoingMailStore.profilesForApp(caller.data));
     } catch {
-      return fail({ code: "mail_unavailable", message: "Outgoing mail profiles are unavailable.", status: 500 });
+      return fail(failure(undefined));
+    }
+  },
+  async send(message: MailMessage, options?: { signal?: AbortSignal }): Promise<Result<MailRecord, MailServiceError>> {
+    const caller = identity();
+    if (!caller.ok) {
+      cancelMailStreams(message?.attachments);
+      const appId = getProcessApplicationId();
+      if (appId) await recordMailSend(appId, message, undefined, undefined, caller.error.code).catch(() => {});
+      return caller;
+    }
+    const parsed = MailMessageSchema.safeParse(message);
+    if (!parsed.success) {
+      cancelMailStreams(message?.attachments);
+      await recordMailSend(caller.data, message, undefined, undefined, "bad_input").catch(() => {});
+      return fail({ code: "bad_input", message: "Invalid outgoing mail message.", status: 400 });
+    }
+    try {
+      return ok(await sendMail(caller.data, parsed.data, options?.signal));
+    } catch (error) {
+      cancelMailStreams(message?.attachments);
+      const issue = failure(error);
+      await recordMailSend(caller.data, parsed.data, undefined, undefined, issue.code).catch(() => {});
+      return fail(issue);
+    }
+  },
+  async list(filter: MailFilter = {}, page: MailPageParams = {}): Promise<Result<MailPage, MailServiceError>> {
+    const caller = identity();
+    if (!caller.ok) return caller;
+    const parsedFilter = MailFilterSchema.safeParse(filter);
+    const parsedPage = MailPageParamsSchema.safeParse(page);
+    if (!parsedFilter.success || !parsedPage.success)
+      return fail({ code: "bad_input", message: "Invalid outgoing mail filter or page.", status: 400 });
+    try {
+      return ok(await outgoingMailMessages.list({ ...parsedFilter.data, app: caller.data }, parsedPage.data));
+    } catch (error) {
+      return fail(failure(error));
     }
   },
 };

package/src/services/outgoing-mail/message.ts

@@ -0,0 +1,14 @@
+import type { RequestActor } from "../../contracts/shared";
+
+export const mailBackoffMs = (attempt: number): number => Math.min(60_000 * 2 ** Math.min(Math.max(attempt - 1, 0), 6), 60 * 60_000);
+export const mailMessageId = (id: string, address: string): string => `<${id}@${address.slice(address.lastIndexOf("@") + 1)}>`;
+export const mailEnvelope = (profile: { fromAddress: string; fromName: string | null }, appName: string, fromName?: string | null) => ({
+  from: { address: profile.fromAddress, name: fromName ?? profile.fromName ?? appName },
+  envelope: { from: profile.fromAddress },
+});
+export const mailActorSnapshot = (actor?: RequestActor) => {
+  if (!actor) return undefined;
+  return actor.kind === "user"
+    ? { type: actor.kind, id: actor.user.id, name: actor.user.displayName || actor.user.uid }
+    : { type: actor.kind, id: actor.serviceAccount.id, name: actor.serviceAccount.name };
+};