@softure-ai/mailing 0.2.2 → 0.2.4

package/src/cli/run.ts

@@ -18,9 +18,9 @@ import { listConfiguredCampaignRecipients, planCampaign, sendCampaign, type Camp
 import type { DeliveryContext, RunHaltReason } from "../server/deliveries.js";
 import { checkSenderDns, getSenderDomain, resendReturnPath, type DmarcAlignment, type DmarcExpectation, type DmarcPolicy, type DnsCheck, type ResolveCname, type ResolveMx, type ResolveTxt, type ReturnPathHost } from "../server/dns.js";
 import { checkImportedDeliveries, importDeliveries, type ImportedDelivery, type ImportProblem } from "../server/import-deliveries.js";
-import { maskAddress, redactUnsubscribeSignatures } from "../server/operator-output.js";
+import { formatMailPreview, maskAddress } from "../server/operator-output.js";
 import { getMailingOptions, resolveMailKind } from "../server/options.js";
-import { previewMail, sendMail } from "../server/send-mail.js";
+import { previewMail, sendMail, sendMailUnchecked } from "../server/send-mail.js";
 import { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV, type Env } from "../server/unsubscribe-link.js";
 
 export interface CliOutput {
@@ -85,7 +85,8 @@ test      Sends one mail to testAddress of the mailing options, and to no one el
           campaign in <content-file> (without the ledger: it can be sent again), or a short
           fixed test mail.
   --kind <kind>        the mail's kind (default: the file's, else transactional); list kinds
-                       get the unsubscribe footer and headers
+                       get the unsubscribe footer and headers, and are refused for a test address
+                       that unsubscribed; without a database that check is skipped
   --preview            print the mail instead of sending it
 
 import    Writes deliveries the app made before it adopted the module into the ledger, so
@@ -635,17 +636,7 @@ const PREVIEW_ADDRESS = "recipient@example.com";
 
 /** The mail as the provider would get it, one output line per line, the address masked and signatures redacted. */
 function printPreview(message: ProviderMessage, output: CliOutput): void {
-  const headers = [
-    `From: ${message.from}`,
-    `To: ${maskAddress(message.to)}`,
-    ...(message.replyTo === null ? [] : [`Reply-To: ${maskAddress(message.replyTo)}`]),
-    `Subject: ${message.subject}`,
-    ...Object.entries(message.headers).map(([name, value]) => `${name}: ${value}`),
-  ];
-  const sections = [`--- preview (addresses masked, link signatures redacted) ---`, ...headers, "", "--- text ---", message.text];
-  if (message.html !== null) sections.push("--- html ---", message.html);
-  sections.push("--- end of preview ---");
-  for (const line of redactUnsubscribeSignatures(sections.join("\n")).split("\n")) output.log(line);
+  for (const line of formatMailPreview(message)) output.log(line);
 }
 
 /** The fixed mail of `softure-mail test` without a content file. Operator text: the test address is the operator's. */
@@ -687,10 +678,8 @@ async function runTest(command: Extract<Command, { kind: "test" }>, options: Run
     return EXIT_OK;
   }
   if (kind === TRANSACTIONAL_KIND) return reportTestSend(await sendMail({ config }, mail), { masked, kind }, output);
-  if (config.database === null) {
-    output.error("softure-mail test: list mail needs the database (its suppression list); set database.url in softure.config");
-    return EXIT_FAILED;
-  }
+  // The test address is the operator's own: without a database (CI, an operator machine) its suppression check guards nothing.
+  if (config.database === null) return reportTestSend(await sendMailUnchecked(config, mail), { masked, kind, unchecked: true }, output);
   let opened: CommandDatabase;
   try {
     opened = await openDatabase(config.database, options.openDatabase);
@@ -705,9 +694,10 @@ async function runTest(command: Extract<Command, { kind: "test" }>, options: Run
   }
 }
 
-function reportTestSend(result: Awaited<ReturnType<typeof sendMail>>, sent: { readonly masked: string; readonly kind: string }, output: CliOutput): number {
+function reportTestSend(result: Awaited<ReturnType<typeof sendMail>>, sent: { readonly masked: string; readonly kind: string; readonly unchecked?: boolean }, output: CliOutput): number {
   if (result.ok) {
-    output.log(`test mail (${sent.kind}) sent to ${sent.masked}; provider message id ${result.value.id}`);
+    const note = sent.unchecked === true ? "; no database, so the suppression list was not checked" : "";
+    output.log(`test mail (${sent.kind}) sent to ${sent.masked}; provider message id ${result.value.id}${note}`);
     return EXIT_OK;
   }
   const status = result.httpStatus === undefined ? "" : ` (HTTP ${String(result.httpStatus)})`;

package/src/contract.ts

@@ -138,6 +138,31 @@ export interface OutgoingMail {
    * list kind.
    */
   readonly kind?: string;
+  /**
+   * Files sent with the mail, e.g. an invoice PDF or a report. Checked before anything leaves the process: at most
+   * `mailing({ attachments: { maxCount } })` files and `maxTotalBytes` bytes in all, a plain filename and a content
+   * type from the allow-list. The provider must declare `supportsAttachments`. Never logged: a failure logs the count,
+   * the content types and the sizes only.
+   */
+  readonly attachments?: readonly MailAttachment[];
+}
+
+/** One file attached to a mail. */
+export interface MailAttachment {
+  /** The name the recipient sees, e.g. `invoice-2026-10.pdf`: 1 to 255 characters, no path separators or control characters. */
+  readonly filename: string;
+  /** The MIME type, e.g. `application/pdf`; it must be on the module's allow-list (`attachments.contentTypes`). */
+  readonly contentType: string;
+  /** The file's bytes, at least one. A Node `Buffer` is a `Uint8Array` too. */
+  readonly content: Uint8Array;
+}
+
+/** What an attachment looks like in a log, a dry run or an app's own records: everything but the bytes. */
+export interface AttachmentSummary {
+  readonly filename: string;
+  readonly contentType: string;
+  /** The content's length in bytes. */
+  readonly size: number;
 }
 
 export interface SendMailOptions {
@@ -174,6 +199,8 @@ export interface ProviderMessage {
   readonly html: string | null;
   readonly headers: Readonly<Record<string, string>>;
   readonly idempotencyKey: string | null;
+  /** The mail's attachments, only when it has any; given only to a provider that declares `supportsAttachments`. */
+  readonly attachments?: readonly MailAttachment[];
 }
 
 /**
@@ -194,5 +221,11 @@ export type ProviderFailureStatus = "rejected" | "unavailable" | "refused" | "qu
 export interface MailProvider {
   /** A short lowercase name for logs and `SentMail.provider`. */
   readonly name: string;
+  /**
+   * True when `send` delivers `ProviderMessage.attachments`. Without it, a mail with attachments is refused as
+   * `mailing.invalid_input` before the provider is called, so an adapter written before attachments existed never
+   * drops a file silently.
+   */
+  readonly supportsAttachments?: boolean;
   send(message: ProviderMessage, context: { readonly signal: AbortSignal }): Promise<ProviderOutcome>;
 }

package/src/index.ts

@@ -17,7 +17,7 @@ export const MODULE_ID = "mailing";
 export const mailing = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.2.2",
+    version: "0.2.4",
     dependsOn: { jobs: "*?" },
     dbSchema: "mailing",
     tables: ["suppressions", "campaigns", "deliveries"],
@@ -64,14 +64,25 @@ export {
   MAX_SUBJECT_LENGTH,
   RESERVED_HEADERS,
 } from "./address.js";
+export {
+  DEFAULT_ATTACHMENT_CONTENT_TYPES,
+  DEFAULT_MAX_ATTACHMENTS,
+  describeAttachments,
+  isAttachmentFilename,
+  MAX_ATTACHMENT_BYTES,
+  MAX_ATTACHMENT_FILENAME_LENGTH,
+  type AttachmentLimits,
+} from "./attachments.js";
 export { HALTING_ERROR_CODES, TRANSACTIONAL_KIND } from "./contract.js";
 export type {
+  AttachmentSummary,
   CampaignRecipient,
   CampaignRecipientFilter,
   CampaignRecipientSource,
   DeliveryJobErrorCode,
   LegacyUnsubscribe,
   LegacyUnsubscribeParams,
+  MailAttachment,
   MailingErrorCode,
   MailProvider,
   OnUnsubscribedHook,

package/src/jobs/delivery-job.ts

@@ -1,7 +1,8 @@
 // Deliveries through @softure-ai/jobs: the app enqueues a delivery in its own transaction and the jobs worker sends
 // it, retrying while the provider is unavailable. The job runs at least once; the delivery ledger and its idempotency
 // key make the mail go out once. The job payload holds the ledger scope and the app's ids, never the mail: the
-// handler builds the mail from the app's data when it runs.
+// handler builds the mail from the app's data when it runs. Attachments too: the app keeps the file in its own storage
+// (with its own retention) and `buildMail` loads it by reference on every attempt; bytes in the payload are refused.
 import { err, ok, type Ok } from "@softure-ai/core";
 import { defineJobHandler, failJob, retryJobLater, type JobFailure, type JobHandler, type JobHandlerContext } from "@softure-ai/jobs";
 import { enqueueJob, type EnqueuedJob, type JobsContext } from "@softure-ai/jobs/server";
@@ -22,7 +23,10 @@ export interface EnqueueDeliveryInput<TPayload> {
    * dedup key: while a job for this scope is pending or running, a second enqueue returns it.
    */
   readonly scope: string;
-  /** The app's ids the handler builds the mail from. JSON; no addresses, names or tokens. */
+  /**
+   * The app's ids the handler builds the mail from. JSON; no addresses, names or tokens, and no file content: an
+   * attachment is referenced by the app's id for it and loaded in `buildMail`.
+   */
   readonly payload: TPayload;
   /** When the job becomes due; default now. Not together with `delaySeconds`. */
   readonly runAt?: Date;
@@ -33,12 +37,18 @@ export interface EnqueueDeliveryInput<TPayload> {
 
 /**
  * Enqueues a delivery. Pass the caller's transaction as `ctx.db`, so the job exists exactly when the caller's own
- * change commits. Throws for a malformed scope, and like `enqueueJob` (an unknown queue, a database failure).
+ * change commits. Throws for a malformed scope, for a payload that holds binary data (a `Uint8Array`, `Buffer` or
+ * `ArrayBuffer`: reference the file instead), and like `enqueueJob` (an unknown queue, a database failure).
  */
 export async function enqueueDelivery<TPayload>(ctx: JobsContext, input: EnqueueDeliveryInput<TPayload>): Promise<EnqueuedJob> {
   if (!isDeliveryScope(input.scope)) {
     throw new Error(`@softure-ai/mailing: enqueueDelivery scope "${input.scope}" must be lowercase letters, digits and ._:- (at most 128 characters)`);
   }
+  if (hasBinaryData(input.payload)) {
+    throw new Error(
+      `@softure-ai/mailing: enqueueDelivery payload for scope "${input.scope}" holds binary data; store the file in the app and pass its id, then load it in buildMail`,
+    );
+  }
   return enqueueJob(ctx, {
     queue: input.queue,
     payload: { scope: input.scope, payload: input.payload },
@@ -49,6 +59,15 @@ export async function enqueueDelivery<TPayload>(ctx: JobsContext, input: Enqueue
   });
 }
 
+/** True when `value` holds an `ArrayBuffer` or a view of one (`Uint8Array`, `Buffer`) anywhere in its objects and arrays. */
+function hasBinaryData(value: unknown, seen: Set<object> = new Set()): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return true;
+  if (seen.has(value)) return false;
+  seen.add(value);
+  return Object.values(value).some((item) => hasBinaryData(item, seen));
+}
+
 /** What `buildMail` receives besides the app's payload: the job's context and the delivery's scope. */
 export interface DeliveryJobContext extends JobHandlerContext {
   readonly scope: string;
@@ -60,7 +79,8 @@ export interface DeliveryJobHandlerOptions<TSchema extends z.ZodType> {
   /**
    * Builds the mail from the app's data. Called on every attempt, before the ledger is read, so it must have no side
    * effects and return the same mail each time: a different body under the same idempotency key is refused by the
-   * provider. Return `null` when there is nothing to send any more (the account is gone); the job then succeeds.
+   * provider. Attachments are loaded here from the app's storage by the ids in the payload; keep the file until the
+   * job is done. Return `null` when there is nothing to send any more (the account is gone); the job then succeeds.
    */
   readonly buildMail: (payload: z.output<TSchema>, context: DeliveryJobContext) => Promise<OutgoingMail | null>;
   /** The ledger's claim windows; `maxAttempts` is the job's, so the ledger does not count attempts here. */

package/src/options.ts

@@ -1,6 +1,7 @@
 // The options an app passes to `mailing({ ... })` in softure.config.ts, parsed at startup.
 import { z } from "zod";
 import { isMailbox, isMailKind, isSingleAddress } from "./address.js";
+import { DEFAULT_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENTS, getContentTypeEssence, isContentType, MAX_ATTACHMENT_BYTES } from "./attachments.js";
 import type { CampaignRecipientFilter, CampaignRecipientSource, LegacyUnsubscribe, MailProvider, OnUnsubscribedHook } from "./contract.js";
 
 export const DEFAULT_TIMEOUT_MS = 10_000;
@@ -55,6 +56,22 @@ function isMailProvider(value: unknown): value is MailProvider {
   return typeof candidate.name === "string" && candidate.name !== "" && typeof candidate.send === "function";
 }
 
+const attachmentsOptionsSchema = z.strictObject({
+  /** Files per mail, 1 to 100. Default 10. */
+  maxCount: z.number().int().min(1).max(100).default(DEFAULT_MAX_ATTACHMENTS),
+  /** Raw bytes of all attachments of one mail, at most (and by default) 28,000,000: about 37.3 MB base64. */
+  maxTotalBytes: z.number().int().min(1).max(MAX_ATTACHMENT_BYTES).default(MAX_ATTACHMENT_BYTES),
+  /**
+   * The content types an attachment may have, e.g. `["application/pdf"]`; replaces the default list
+   * (`DEFAULT_ATTACHMENT_CONTENT_TYPES`). Compared without parameters and case.
+   */
+  contentTypes: z
+    .array(z.string().trim().refine(isContentType, "must be a MIME type such as application/pdf"))
+    .min(1)
+    .transform((types) => [...new Set(types.map(getContentTypeEssence))])
+    .default([...DEFAULT_ATTACHMENT_CONTENT_TYPES]),
+});
+
 export const mailingOptionsSchema = z.strictObject({
   /**
    * The sender of every mail: `hello@example.com` or `Plan <hello@example.com>`. It must be on a
@@ -108,6 +125,8 @@ export const mailingOptionsSchema = z.strictObject({
    * idempotency window. More than `staleClaimMs`, at most 30 days.
    */
   uncertainClaimMs: z.number().int().min(60_000).max(30 * 24 * HOUR_MS).default(DEFAULT_UNCERTAIN_CLAIM_MS),
+  /** Limits on attachments: count, total size and allowed content types. Defaults fit Resend's 40 MB cap. */
+  attachments: attachmentsOptionsSchema.prefault({}),
 }).refine((options) => options.uncertainClaimMs > options.staleClaimMs, { message: "must be more than staleClaimMs", path: ["uncertainClaimMs"] });
 
 export type MailingOptionsInput = z.input<typeof mailingOptionsSchema>;

package/src/providers/resend.ts

@@ -32,6 +32,7 @@ export function resend(options: ResendOptions = {}): MailProvider {
   const endpoint = options.endpoint ?? RESEND_ENDPOINT;
   return {
     name: "resend",
+    supportsAttachments: true,
     send: async (message, { signal }) => {
       const apiKey = (options.apiKey ?? process.env[RESEND_API_KEY_ENV] ?? "").trim();
       if (apiKey === "") {
@@ -65,6 +66,15 @@ function toResendBody(message: ProviderMessage): Record<string, unknown> {
     ...(message.html === null ? {} : { html: message.html }),
     ...(message.replyTo === null ? {} : { reply_to: message.replyTo }),
     ...(Object.keys(message.headers).length === 0 ? {} : { headers: message.headers }),
+    ...(message.attachments === undefined || message.attachments.length === 0
+      ? {}
+      : {
+          attachments: message.attachments.map((attachment) => ({
+            filename: attachment.filename,
+            content: Buffer.from(attachment.content.buffer, attachment.content.byteOffset, attachment.content.byteLength).toString("base64"),
+            content_type: attachment.contentType,
+          })),
+        }),
   };
 }
 

package/src/server/deliveries.ts

@@ -167,7 +167,7 @@ export async function forecastDelivery(ctx: DeliveryContext, delivery: Delivery,
     if (age <= windows.staleClaimMs) return { status: "in-flight" };
     if (age > windows.uncertainClaimMs && !windows.retakeUncertain) return { status: "uncertain" };
   }
-  if (!validateMail(delivery.mail).ok) return { status: "rejected", reason: "mailing.invalid_input" };
+  if (!validateMail(delivery.mail, {}, getMailingOptions(ctx.config).attachments).ok) return { status: "rejected", reason: "mailing.invalid_input" };
   if (kind !== TRANSACTIONAL_KIND && (await isSuppressed(ctx, delivery.mail.to))) return { status: "rejected", reason: "mailing.suppressed" };
   return { status: "send" };
 }

package/src/server/index.ts

@@ -61,7 +61,7 @@ export {
   type ImportSummary,
 } from "./import-deliveries.js";
 export { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders, SIGNATURE_SEPARATOR } from "./list-mail.js";
-export { maskAddress, redactUnsubscribeSignatures } from "./operator-output.js";
+export { formatMailPreview, maskAddress, redactUnsubscribeSignatures } from "./operator-output.js";
 export { getMailingModule, getMailingOptions, getMailingRoutes, resolveMailKind, type MailingRoutes } from "./options.js";
 export { runDeliveries, type DeliveryRunInput, type DeliveryRunSummary, type RunDeliveriesOptions } from "./run-deliveries.js";
 export { previewMail, sendMail, type MailContext, type MailPreviewFailure, type MailPreviewResult, type PreviewMailOptions } from "./send-mail.js";

package/src/server/operator-output.ts

@@ -1,6 +1,8 @@
 // What an operator's terminal may show of a mail: addresses masked, link signatures redacted. Command output ends
 // up in shell history, CI logs and pasted chat messages; a full address is personal data, and a signed unsubscribe
 // link lets whoever holds it unsubscribe that address.
+import { describeAttachments } from "../attachments.js";
+import type { ProviderMessage } from "../contract.js";
 import { SIGNATURE_PARAM } from "./unsubscribe-link.js";
 
 /** `ada@example.org` becomes `a**@example.org`: the first character of the local part, then one `*` per other. */
@@ -18,3 +20,25 @@ const SIGNATURE = new RegExp(`([?&](?:amp;)?${SIGNATURE_PARAM}=)[A-Za-z0-9_-]+`,
 export function redactUnsubscribeSignatures(text: string): string {
   return text.replace(SIGNATURE, "$1<signature>");
 }
+
+/**
+ * A mail as the provider would get it (`previewMail`'s value), as terminal lines: the addresses masked, link
+ * signatures redacted, and each attachment by filename, content type and size, never its bytes.
+ */
+export function formatMailPreview(message: ProviderMessage): string[] {
+  const headers = [
+    `From: ${message.from}`,
+    `To: ${maskAddress(message.to)}`,
+    ...(message.replyTo === null ? [] : [`Reply-To: ${maskAddress(message.replyTo)}`]),
+    `Subject: ${message.subject}`,
+    ...Object.entries(message.headers).map(([name, value]) => `${name}: ${value}`),
+  ];
+  const sections = [`--- preview (addresses masked, link signatures redacted) ---`, ...headers, "", "--- text ---", message.text];
+  if (message.html !== null) sections.push("--- html ---", message.html);
+  const attachments = describeAttachments(message.attachments ?? []);
+  if (attachments.length > 0) {
+    sections.push("--- attachments ---", ...attachments.map(({ filename, contentType, size }) => `${filename} (${contentType}, ${String(size)} bytes)`));
+  }
+  sections.push("--- end of preview ---");
+  return redactUnsubscribeSignatures(sections.join("\n")).split("\n");
+}

package/src/server/send-mail.ts

@@ -1,12 +1,15 @@
 // Sends one mail through the configured provider, with three rules: it never throws for a failed
 // send (every failure is a result), nothing of the mail (address, subject, body, key) reaches a log
 // or the result, and `headers` cannot replace the envelope or the sender (a mail's own reply-to is
-// the `replyTo` field, checked like `to`). List mail (any kind but `transactional`) also gets a signed unsubscribe
+// the `replyTo` field, checked like `to`). Attachments go only to a provider that declares it delivers them, and a
+// log line describes them by count, content type and size, never by name or content. List mail (any kind but `transactional`) also gets a signed unsubscribe
 // link in a footer and the RFC 8058 headers, and is refused for a recipient who unsubscribed.
 import { err, type Err, ok, type Ok, selectMessages, type SoftureConfig } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
+import { getContentTypeEssence } from "../attachments.js";
 import {
   TRANSACTIONAL_KIND,
+  type MailAttachment,
   type MailingErrorCode,
   type MailProvider,
   type OutgoingMail,
@@ -42,29 +45,56 @@ export interface MailContext {
  * Throws only when the module is not enabled, or for list mail without `context.db`.
  */
 export async function sendMail(context: MailContext, mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
-  const { provider, timeoutMs } = getMailingOptions(context.config);
+  const { provider, timeoutMs, attachments: limits } = getMailingOptions(context.config);
 
-  const validation = validateMail(mail, options);
+  const validation = validateMail(mail, options, limits);
   if (!validation.ok) {
     logFailure(provider, "mailing.invalid_input", { fields: validation.fields });
     return err("mailing.invalid_input");
   }
   const valid = validation.value;
+  if (!canCarryAttachments(provider, valid)) return refuseAttachments(provider, valid);
   const secret = readUnsubscribeSecrets().current;
   if (valid.kind !== TRANSACTIONAL_KIND) {
     const refusal = await checkListMail(context, valid, secret);
     if (refusal !== null) {
-      logFailure(provider, refusal.error, { cause: refusal.cause });
+      logFailure(provider, refusal.error, { cause: refusal.cause, attachments: valid.attachments });
       return err(refusal.error);
     }
   }
 
-  const outcome = await callProvider(provider, composeMessage(context.config, valid, secret), timeoutMs);
+  return deliver(provider, composeMessage(context.config, valid, secret), timeoutMs);
+}
+
+/**
+ * `sendMail` without the suppression check, for `softure-mail test` without a database: its recipient is always the
+ * operator's own `testAddress`. List mail still needs the secret. Internal: not exported from `/server`, so no app
+ * code can send list mail to a real recipient past the suppression list.
+ */
+export async function sendMailUnchecked(config: SoftureConfig, mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
+  const { provider, timeoutMs, attachments: limits } = getMailingOptions(config);
+  const validation = validateMail(mail, options, limits);
+  if (!validation.ok) {
+    logFailure(provider, "mailing.invalid_input", { fields: validation.fields });
+    return err("mailing.invalid_input");
+  }
+  if (!canCarryAttachments(provider, validation.value)) return refuseAttachments(provider, validation.value);
+  const secret = readUnsubscribeSecrets().current;
+  if (validation.value.kind !== TRANSACTIONAL_KIND && secret === null) {
+    logFailure(provider, "mailing.unavailable", { cause: "no_unsubscribe_secret", attachments: validation.value.attachments });
+    return err("mailing.unavailable");
+  }
+  return deliver(provider, composeMessage(config, validation.value, secret), timeoutMs);
+}
+
+/** Hands `message` to the provider and maps its outcome to the result, logging a failure. */
+async function deliver(provider: MailProvider, message: ProviderMessage, timeoutMs: number): Promise<SendMailResult> {
+  const outcome = await callProvider(provider, message, timeoutMs);
   if (outcome.status === "sent") {
     return ok({ id: outcome.id, provider: provider.name });
   }
   const code = FAILURE_CODES[outcome.status];
-  logFailure(provider, code, { status: outcome.httpStatus });
+  logFailure(provider, code, { status: outcome.httpStatus, attachments: message.attachments ?? [] });
   return {
     ...err(code),
     ...(outcome.httpStatus === undefined ? {} : { httpStatus: outcome.httpStatus }),
@@ -72,6 +102,16 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
   };
 }
 
+/** False for a mail with attachments and a provider that does not declare it delivers them. */
+function canCarryAttachments(provider: MailProvider, mail: ValidMail): boolean {
+  return mail.attachments.length === 0 || provider.supportsAttachments === true;
+}
+
+function refuseAttachments(provider: MailProvider, mail: ValidMail): SendMailResult {
+  logFailure(provider, "mailing.invalid_input", { fields: ["attachments"], cause: "provider_without_attachments", attachments: mail.attachments });
+  return err("mailing.invalid_input");
+}
+
 /** Why `previewMail` cannot render a mail: invalid input (with the fields), or list mail without the secret. */
 export type MailPreviewFailure =
   | (Err<"mailing.invalid_input"> & { readonly fields: readonly string[] })
@@ -85,14 +125,15 @@ export interface PreviewMailOptions extends SendMailOptions {
 }
 
 /**
- * Exactly what `sendMail` would hand the provider for `mail`: the sender, the reply-to, and for list mail the
- * footer with a link signed for `mail.to` and the RFC 8058 headers. Sends nothing, logs nothing and needs no
- * database: it does not check the suppression list, so it renders a mail `sendMail` would refuse as suppressed.
+ * Exactly what `sendMail` would hand the provider for `mail`: the sender, the reply-to, the attachments, and for list
+ * mail the footer with a link signed for `mail.to` and the RFC 8058 headers. Sends nothing, logs nothing and needs no
+ * database: it does not check the suppression list, so it renders a mail `sendMail` would refuse as suppressed, nor
+ * whether the provider delivers attachments.
  * The links in it are credentials for `mail.to`. Throws only when the module is not enabled.
  */
 export function previewMail(config: SoftureConfig, mail: OutgoingMail, options: PreviewMailOptions = {}): MailPreviewResult {
   const { env, ...sendOptions } = options;
-  const validation = validateMail(mail, sendOptions);
+  const validation = validateMail(mail, sendOptions, getMailingOptions(config).attachments);
   if (!validation.ok) return { ...err("mailing.invalid_input"), fields: validation.fields };
   const secret = readUnsubscribeSecrets(env).current;
   if (validation.value.kind !== TRANSACTIONAL_KIND && secret === null) return { ...err("mailing.unavailable"), cause: "no_unsubscribe_secret" };
@@ -134,8 +175,8 @@ async function checkListMail(context: MailContext, mail: ValidMail, secret: stri
  */
 function composeMessage(config: SoftureConfig, mail: ValidMail, secret: string | null): ProviderMessage {
   const { from, replyTo } = getMailingOptions(config);
-  const { idempotencyKey, kind, replyTo: mailReplyTo, ...content } = mail;
-  const envelope = { from, replyTo: mailReplyTo ?? replyTo ?? null, idempotencyKey };
+  const { idempotencyKey, kind, replyTo: mailReplyTo, attachments, ...content } = mail;
+  const envelope = { from, replyTo: mailReplyTo ?? replyTo ?? null, idempotencyKey, ...(attachments.length === 0 ? {} : { attachments }) };
   if (kind === TRANSACTIONAL_KIND || secret === null) return { ...content, ...envelope };
   const links = buildUnsubscribeLinks(config, mail.to, secret);
   // The module factory merged the dictionaries; their shape is the module's own.
@@ -201,15 +242,21 @@ function isHttpStatus(value: unknown): value is number {
 
 /**
  * The module's only log line. Deliberately takes nothing but the provider, the code, a status,
- * field names and a fixed cause: anything added "for diagnosis" is where an address leaks first.
+ * field names, a fixed cause and the attachments' content types and sizes: anything added "for
+ * diagnosis" is where an address leaks first. Filenames stay out like the subject: they are the
+ * app's text and often name a person or an invoice.
  */
 function logFailure(
   provider: MailProvider,
   code: MailingErrorCode,
-  details: { readonly status?: number; readonly fields?: readonly string[]; readonly cause?: string },
+  details: { readonly status?: number; readonly fields?: readonly string[]; readonly cause?: string; readonly attachments?: readonly MailAttachment[] },
 ): void {
   const parts = [`provider=${provider.name}`, `reason=${code.slice("mailing.".length)}`, `status=${details.status === undefined ? "none" : String(details.status)}`];
   if (details.fields !== undefined) parts.push(`fields=${details.fields.join(",")}`);
   if (details.cause !== undefined) parts.push(`cause=${details.cause}`);
+  if (details.attachments !== undefined && details.attachments.length > 0) {
+    const attachments = details.attachments.map((attachment) => `${getContentTypeEssence(attachment.contentType)}:${String(attachment.content.byteLength)}`);
+    parts.push(`attachments=${attachments.join(",")}`);
+  }
   console.error(`mailing: send failed ${parts.join(" ")}`);
 }

package/src/server/validate-mail.ts

@@ -2,7 +2,8 @@
 // process. Failures name the fields, never their values (an address is personal data).
 import { z } from "zod";
 import { hasLineBreak, isHeaderName, isIdempotencyKey, isListMailHeader, isMailKind, isReservedHeader, isSingleAddress, MAX_SUBJECT_LENGTH } from "../address.js";
-import { TRANSACTIONAL_KIND } from "../contract.js";
+import { DEFAULT_ATTACHMENT_LIMITS, getContentTypeEssence, isAttachmentFilename, isContentType, type AttachmentLimits } from "../attachments.js";
+import { TRANSACTIONAL_KIND, type MailAttachment } from "../contract.js";
 
 const headersSchema = z.record(z.string(), z.string()).superRefine((headers, context) => {
   for (const [name, value] of Object.entries(headers)) {
@@ -12,7 +13,24 @@ const headersSchema = z.record(z.string(), z.string()).superRefine((headers, con
   }
 });
 
-const mailSchema = z.object({
+const attachmentSchema = z.object({
+  filename: z.string().refine(isAttachmentFilename),
+  contentType: z.string().trim().refine(isContentType),
+  // A Node Buffer is a Uint8Array too; an empty file is almost always a caller's bug.
+  content: z.custom<Uint8Array>((value) => value instanceof Uint8Array && value.byteLength > 0),
+});
+
+/** The attachments within `limits`: count, total bytes and an allowed content type for each. */
+function createAttachmentsSchema(limits: AttachmentLimits) {
+  const allowed = new Set(limits.contentTypes);
+  return z
+    .array(attachmentSchema)
+    .max(limits.maxCount)
+    .refine((attachments) => attachments.every((attachment) => allowed.has(getContentTypeEssence(attachment.contentType))))
+    .refine((attachments) => attachments.reduce((total, attachment) => total + attachment.content.byteLength, 0) <= limits.maxTotalBytes);
+}
+
+const mailFields = {
   to: z.string().trim().refine(isSingleAddress),
   subject: z
     .string()
@@ -25,12 +43,28 @@ const mailSchema = z.object({
   headers: headersSchema.optional(),
   replyTo: z.string().trim().refine(isSingleAddress).optional(),
   kind: z.string().refine(isMailKind).default(TRANSACTIONAL_KIND),
-}).superRefine((mail, context) => {
-  // The module writes these two on list mail; a second, unsigned copy would confuse clients.
-  if (mail.kind !== TRANSACTIONAL_KIND && Object.keys(mail.headers ?? {}).some(isListMailHeader)) {
-    context.addIssue({ code: "custom", path: ["headers"], message: "list mail gets its unsubscribe headers from the module" });
+};
+
+function createMailSchema(limits: AttachmentLimits) {
+  return z.object({ ...mailFields, attachments: createAttachmentsSchema(limits).optional() }).superRefine((mail, context) => {
+    // The module writes these two on list mail; a second, unsigned copy would confuse clients.
+    if (mail.kind !== TRANSACTIONAL_KIND && Object.keys(mail.headers ?? {}).some(isListMailHeader)) {
+      context.addIssue({ code: "custom", path: ["headers"], message: "list mail gets its unsubscribe headers from the module" });
+    }
+  });
+}
+
+/** One schema per limits object: the configured limits are parsed once per config, so this builds each once. */
+const mailSchemas = new WeakMap<AttachmentLimits, ReturnType<typeof createMailSchema>>();
+
+function getMailSchema(limits: AttachmentLimits): ReturnType<typeof createMailSchema> {
+  let schema = mailSchemas.get(limits);
+  if (schema === undefined) {
+    schema = createMailSchema(limits);
+    mailSchemas.set(limits, schema);
   }
-});
+  return schema;
+}
 
 const optionsSchema = z.object({
   idempotencyKey: z.string().refine(isIdempotencyKey).optional(),
@@ -47,25 +81,38 @@ export interface ValidMail {
   /** `transactional` or a list kind. */
   readonly kind: string;
   readonly idempotencyKey: string | null;
+  /** Empty when the mail has none. */
+  readonly attachments: readonly MailAttachment[];
 }
 
 export type MailValidation = { readonly ok: true; readonly value: ValidMail } | { readonly ok: false; readonly fields: readonly string[] };
 
 /**
- * Checks one mail and its send options. `fields` lists what failed (`to`, `subject`, `text`,
- * `html`, `headers`, `replyTo`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
+ * Checks one mail and its send options, its attachments against `limits` (default: the module's defaults; `sendMail`
+ * passes the configured ones). `fields` lists what failed (`to`, `subject`, `text`, `html`, `headers`, `replyTo`,
+ * `kind`, `attachments`, `idempotencyKey`, or `mail` when the input is not an object).
  */
-export function validateMail(mail: unknown, options: unknown = {}): MailValidation {
-  const parsedMail = mailSchema.safeParse(mail);
+export function validateMail(mail: unknown, options: unknown = {}, limits: AttachmentLimits = DEFAULT_ATTACHMENT_LIMITS): MailValidation {
+  const parsedMail = getMailSchema(limits).safeParse(mail);
   const parsedOptions = optionsSchema.safeParse(options ?? {});
   if (!parsedMail.success || !parsedOptions.success) {
     const issues = [...(parsedMail.error?.issues ?? []), ...(parsedOptions.error?.issues ?? [])];
     const fields = new Set(issues.map((issue) => (issue.path.length === 0 ? "mail" : String(issue.path[0]))));
     return { ok: false, fields: [...fields] };
   }
-  const { to, subject, text, html, headers, replyTo, kind } = parsedMail.data;
+  const { to, subject, text, html, headers, replyTo, kind, attachments = [] } = parsedMail.data;
   return {
     ok: true,
-    value: { to, subject, text, html: html ?? null, headers: headers ?? {}, replyTo: replyTo ?? null, kind, idempotencyKey: parsedOptions.data.idempotencyKey ?? null },
+    value: {
+      to,
+      subject,
+      text,
+      html: html ?? null,
+      headers: headers ?? {},
+      replyTo: replyTo ?? null,
+      kind,
+      idempotencyKey: parsedOptions.data.idempotencyKey ?? null,
+      attachments,
+    },
   };
 }