@softure-ai/mailing 0.2.3 → 0.2.5

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;
@@ -22,6 +23,13 @@ const RESERVED_LINK_PARAMS: ReadonlySet<string> = new Set(["r", "status"]);
 const LINK_PARAM = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
 
 const MAX_LINK_PARAMS = 8;
+
+/** A name of `mailing({ senders })`, the value of `OutgoingMail.sender`: a letter, then letters, digits, `_` or `-`. */
+export const SENDER_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,31}$/;
+
+const sendersSchema = z
+  .record(z.string(), z.string().trim().refine(isMailbox, "must be an address or Name <address>, e.g. Alerts <alerts@example.com>"))
+  .refine((senders) => Object.keys(senders).every((name) => SENDER_NAME.test(name)), "every name must be a letter, then letters, digits, _ or -, at most 32 characters");
 const linkParamNames = z.array(z.string().regex(LINK_PARAM, "must be a query name: a letter, then letters, digits, _ or -, at most 32 characters"));
 
 /** Both forms of `params`, normalised to required and optional names, with the limits on all names together. */
@@ -55,12 +63,33 @@ 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
    * domain the provider signs (DKIM), or DMARC rejects the mail.
    */
   from: z.string().trim().refine(isMailbox, "must be an address or Name <address>, e.g. Plan <hello@example.com>"),
+  /**
+   * Named extra senders a mail picks with `OutgoingMail.sender`, e.g. `{ alerts: "App <alerts@example.com>" }`. Each
+   * is validated like `from` and must sit on a domain the provider signs; `softure-mail dns` checks every one.
+   */
+  senders: sendersSchema.optional(),
   /** Where replies go; may sit on another domain than `from` (DMARC does not check it). */
   replyTo: z.string().trim().refine(isSingleAddress, "must be one address, e.g. support@example.com").optional(),
   /**
@@ -108,6 +137,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

@@ -13,7 +13,7 @@ import { HALTING_ERROR_CODES, TRANSACTIONAL_KIND, type MailingErrorCode, type Ou
 import { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS } from "../options.js";
 import { deliveries } from "../schema.js";
 import { getMailingOptions } from "./options.js";
-import { sendMail } from "./send-mail.js";
+import { resolveSender, sendMail } from "./send-mail.js";
 import { isSuppressed } from "./suppressions.js";
 import { getRecipientKey } from "./unsubscribe-link.js";
 import { validateMail } from "./validate-mail.js";
@@ -167,7 +167,8 @@ 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" };
+  const validation = validateMail(delivery.mail, {}, getMailingOptions(ctx.config).attachments);
+  if (!validation.ok || resolveSender(ctx.config, validation.value) === null) 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,16 @@
 // 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`; its sender is a name of `mailing({ senders })`, never an
+// address). 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,19 +46,21 @@ 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 (resolveSender(context.config, valid) === null) return refuseSender(provider, valid);
+  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);
     }
   }
@@ -68,15 +74,17 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
  * 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 } = getMailingOptions(config);
-  const validation = validateMail(mail, options);
+  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 (resolveSender(config, validation.value) === null) return refuseSender(provider, validation.value);
+  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" });
+    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);
@@ -89,7 +97,7 @@ async function deliver(provider: MailProvider, message: ProviderMessage, timeout
     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 }),
@@ -97,6 +105,31 @@ async function deliver(provider: MailProvider, message: ProviderMessage, timeout
   };
 }
 
+/** 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;
+}
+
+/**
+ * The sender of `mail`: its named sender of `mailing({ senders })`, `from` when it names none, or `null` when the name
+ * is not configured (the mail must not go out: a request cannot pick a sender the app does not have).
+ */
+export function resolveSender(config: SoftureConfig, mail: Pick<ValidMail, "sender">): string | null {
+  const { from, senders = {} } = getMailingOptions(config);
+  if (mail.sender === null) return from;
+  return Object.hasOwn(senders, mail.sender) ? (senders[mail.sender] ?? null) : null;
+}
+
+function refuseSender(provider: MailProvider, mail: ValidMail): SendMailResult {
+  logFailure(provider, "mailing.invalid_input", { fields: ["sender"], attachments: mail.attachments });
+  return err("mailing.invalid_input");
+}
+
+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[] })
@@ -110,15 +143,17 @@ 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 };
+  if (resolveSender(config, validation.value) === null) return { ...err("mailing.invalid_input"), fields: ["sender"] };
   const secret = readUnsubscribeSecrets(env).current;
   if (validation.value.kind !== TRANSACTIONAL_KIND && secret === null) return { ...err("mailing.unavailable"), cause: "no_unsubscribe_secret" };
   return ok(composeMessage(config, validation.value, secret));
@@ -154,13 +189,16 @@ async function checkListMail(context: MailContext, mail: ValidMail, secret: stri
 }
 
 /**
- * The message the provider receives: the configured sender, the mail's or the configured reply-to, and for list
- * mail the footer and headers signed with `secret` (which the caller checked is set).
+ * The message the provider receives: the resolved sender (see `resolveSender`), the mail's or the configured
+ * reply-to, and for list mail the footer and headers signed with `secret` (which the caller checked is set).
  */
 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 { replyTo } = getMailingOptions(config);
+  const { idempotencyKey, kind, replyTo: mailReplyTo, sender, attachments, ...content } = mail;
+  const from = resolveSender(config, { sender });
+  // Every caller refused an unknown sender before composing.
+  if (from === null) throw new Error("@softure-ai/mailing: composeMessage got a sender the config does not have");
+  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.
@@ -226,15 +264,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,9 @@
 // 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";
+import { SENDER_NAME } from "../options.js";
 
 const headersSchema = z.record(z.string(), z.string()).superRefine((headers, context) => {
   for (const [name, value] of Object.entries(headers)) {
@@ -12,7 +14,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()
@@ -24,13 +43,30 @@ const mailSchema = z.object({
     .optional(),
   headers: headersSchema.optional(),
   replyTo: z.string().trim().refine(isSingleAddress).optional(),
+  sender: z.string().regex(SENDER_NAME).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(),
@@ -44,28 +80,44 @@ export interface ValidMail {
   readonly headers: Readonly<Record<string, string>>;
   /** The mail's own reply-to; null to use the configured one. */
   readonly replyTo: string | null;
+  /** The name of a configured sender; null for `from`. Its value is looked up in the config (`resolveSender`). */
+  readonly sender: string | null;
   /** `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`,
+ * `sender` (its shape only: whether the app configured it is `resolveSender`'s check), `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, sender, 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,
+      sender: sender ?? null,
+      kind,
+      idempotencyKey: parsedOptions.data.idempotencyKey ?? null,
+      attachments,
+    },
   };
 }

package/src/testing/fake-provider.ts

@@ -1,6 +1,6 @@
 // A provider that sends nothing: it captures mail in memory (`provider.sent`) and, with an outbox
 // file, appends each mail as one JSON line for a test in another process (an e2e against
-// `next start`). It honours idempotency keys like a real provider: a repeated key answers the
+// `next start`), attachment bytes as base64. It honours idempotency keys like a real provider: a repeated key answers the
 // first id and captures nothing new.
 import { appendFile } from "node:fs/promises";
 import type { MailProvider, ProviderMessage, ProviderOutcome } from "../contract.js";
@@ -34,6 +34,7 @@ export function fakeMailProvider(options: FakeMailProviderOptions = {}): FakeMai
 
   return {
     name: "fake",
+    supportsAttachments: true,
     get sent() {
       return [...sent];
     },
@@ -54,9 +55,14 @@ export function fakeMailProvider(options: FakeMailProviderOptions = {}): FakeMai
       if (knownId !== undefined) return { status: "sent", id: knownId };
 
       counter += 1;
-      const captured: CapturedMail = { ...message, headers: { ...message.headers }, id: `fake-${String(counter)}-${crypto.randomUUID()}` };
+      const captured: CapturedMail = {
+        ...message,
+        headers: { ...message.headers },
+        ...(message.attachments === undefined ? {} : { attachments: message.attachments.map((attachment) => ({ ...attachment, content: attachment.content.slice() })) }),
+        id: `fake-${String(counter)}-${crypto.randomUUID()}`,
+      };
       if (options.outboxFile !== undefined) {
-        await appendFile(options.outboxFile, `${JSON.stringify(captured)}\n`, "utf8");
+        await appendFile(options.outboxFile, `${JSON.stringify(toOutboxLine(captured))}\n`, "utf8");
       }
       sent.push(captured);
       if (message.idempotencyKey !== null) idsByKey.set(message.idempotencyKey, captured.id);
@@ -64,3 +70,12 @@ export function fakeMailProvider(options: FakeMailProviderOptions = {}): FakeMai
     },
   };
 }
+
+/** A captured mail as one outbox line: attachment bytes as base64 (`readMailOutbox` decodes them). */
+function toOutboxLine(mail: CapturedMail): unknown {
+  if (mail.attachments === undefined) return mail;
+  return {
+    ...mail,
+    attachments: mail.attachments.map((attachment) => ({ ...attachment, content: Buffer.from(attachment.content).toString("base64") })),
+  };
+}

package/src/testing/outbox.ts

@@ -13,6 +13,10 @@ const capturedMailSchema = z.object({
   html: z.string().nullable(),
   headers: z.record(z.string(), z.string()),
   idempotencyKey: z.string().nullable(),
+  // Base64 in the file, bytes again here; lines written before attachments existed have none.
+  attachments: z
+    .array(z.object({ filename: z.string(), contentType: z.string(), content: z.base64().transform((content) => new Uint8Array(Buffer.from(content, "base64"))) }))
+    .optional(),
 });
 
 /** Every mail in the outbox, oldest first, optionally only those to `to`. A missing file is an empty outbox. */
@@ -27,6 +31,12 @@ export async function readMailOutbox(file: string, filter: { readonly to?: strin
   return text
     .split("\n")
     .filter((line) => line !== "")
-    .map((line) => capturedMailSchema.parse(JSON.parse(line)))
+    .map((line) => toCapturedMail(capturedMailSchema.parse(JSON.parse(line))))
     .filter((mail) => filter.to === undefined || mail.to === filter.to);
 }
+
+/** A parsed line without an `attachments: undefined` key, so a mail without attachments equals what was sent. */
+function toCapturedMail(line: z.output<typeof capturedMailSchema>): CapturedMail {
+  const { attachments, ...mail } = line;
+  return attachments === undefined ? mail : { ...mail, attachments };
+}