@sandsoftwaresolutions/mail-kit 0.0.0-stage → 0.1.1

package/src/index.d.ts

@@ -0,0 +1,166 @@
+export interface Address { name: string; address: string }
+export type AddressInput = string | { name?: string; address: string };
+export type AddressesInput = AddressInput | AddressInput[];
+
+export class MailError extends Error {
+  /** invalid_address, invalid_header, invalid_message, invalid_template, invalid_config, no_recipients, auth_failed,
+   *  recipient_rejected, rejected, temporary_failure, rate_limited, timeout, connection_failed, tls_failed,
+   *  tls_unavailable, too_large, delivery_unknown, recipient_not_allowed, send_failed, ... */
+  code: string;
+  /** True when sending the same message again is safe and may work. */
+  retryable: boolean;
+  /** Set by the mailer: how many tries were made. */
+  attempts?: number;
+  responseCode?: number;
+  response?: string;
+}
+
+export interface Attachment {
+  filename: string;
+  content: Buffer | Uint8Array | string;
+  /** "base64" when `content` is a base64 string. */
+  encoding?: "base64" | "utf8";
+  contentType?: string;
+  /** Makes it an inline image: use `<img src="cid:logo">` with `cid: "logo"`. */
+  cid?: string;
+}
+
+export interface MessageInput {
+  from?: AddressInput;
+  to?: AddressesInput;
+  cc?: AddressesInput;
+  bcc?: AddressesInput;
+  replyTo?: AddressesInput;
+  subject: string;
+  html?: string;
+  /** Made from the html when left out. */
+  text?: string;
+  headers?: Record<string, string>;
+  attachments?: Attachment[];
+  /** Adds List-Unsubscribe and the one-click header. */
+  unsubscribe?: { url?: string; mailto?: string };
+  /** Default true: adds `Auto-Submitted: auto-generated`, which stops out-of-office replies. */
+  autoSubmitted?: boolean;
+  messageId?: string;
+  date?: Date;
+  /** Bounce address, if different from `from`. */
+  envelopeFrom?: string;
+  /** Default 50. */
+  maxRecipients?: number;
+}
+
+export interface PreparedMessage {
+  from: Address; to: Address[]; cc: Address[]; bcc: Address[]; replyTo: Address[];
+  subject: string; html?: string; text: string;
+  headers: Record<string, string>;
+  attachments: { filename: string; content: Buffer; contentType: string; cid?: string }[];
+  messageId: string; date: Date;
+  envelope: { from: string; to: string[] };
+  /** The complete RFC 5322 message, all CRLF, 7-bit. */
+  readonly raw: Buffer;
+}
+
+export interface SendResult {
+  id: string; messageId: string; accepted: string[]; rejected: string[]; response?: string;
+  attempts?: number; transport?: string;
+}
+
+export interface Transport {
+  name: string;
+  send(message: PreparedMessage | MessageInput): Promise<SendResult>;
+  verify?(): Promise<unknown>;
+}
+
+export function isEmail(value: unknown): boolean;
+export function normalizeAddress(address: string): string;
+export function parseAddress(input: AddressInput): Address;
+export function parseAddressList(input?: AddressesInput): Address[];
+export function encodeWords(text: string): string;
+export function formatAddress(address: Address): string;
+export function prepareMessage(input: MessageInput, defaults?: Partial<MessageInput>): PreparedMessage;
+export function quotedPrintable(text: string): string;
+
+export function escapeHtml(value: unknown): string;
+export function htmlToText(html: string): string;
+export function wrapText(text: string, width?: number): string;
+export function extractLinks(content: string): string[];
+
+export type Block =
+  | { type: "heading"; text: string; level: 1 | 2 }
+  | { type: "paragraph" | "note"; text: string }
+  | { type: "button"; label: string; url: string }
+  | { type: "code"; value: string; caption?: string }
+  | { type: "list"; items: string[]; ordered: boolean }
+  | { type: "table"; rows: [string, string][]; total: boolean }
+  | { type: "divider" }
+  | { type: "image"; src: string; alt: string; width?: number };
+
+export const block: {
+  heading(text: string, level?: 1 | 2): Block;
+  paragraph(text: string): Block;
+  button(label: string, url: string): Block;
+  code(value: string, caption?: string): Block;
+  list(items: string[], options?: { ordered?: boolean }): Block;
+  table(rows: [string, string][], options?: { total?: boolean }): Block;
+  note(text: string): Block;
+  divider(): Block;
+  image(src: string, alt: string, options?: { width?: number }): Block;
+};
+
+export interface EmailOptions {
+  subject: string;
+  /** Preview text shown next to the subject in the inbox. */
+  preheader?: string;
+  /** Strings are paragraphs. Text blocks understand **bold**, `code` and [label](https://url). */
+  blocks: (Block | string)[];
+  footer?: string | string[];
+  lang?: string;
+  brand?: { name?: string; url?: string; logoUrl?: string; color?: string; buttonTextColor?: string; textColor?: string; background?: string; font?: string };
+}
+export interface Mail { subject: string; html: string; text: string }
+export function email(options: EmailOptions): Mail;
+/** Escape a name or any outside text before putting it in a block, so it cannot turn into a link, bold text or code. */
+export function escapeMarkup(value: unknown): string;
+export function preview(mail: Mail): string;
+export function lintEmail(mail: MessageInput | PreparedMessage): { level: "warning" | "info"; message: string }[];
+
+export interface SmtpOptions {
+  host: string;
+  /** Default 587 (465 when security is "tls"). */
+  port?: number;
+  /** "tls" = encrypted from the start (port 465), "starttls" = must upgrade or fail (default), "none" = no encryption. */
+  security?: "tls" | "starttls" | "none";
+  user?: string;
+  pass?: string;
+  allowInsecureAuth?: boolean;
+  timeoutMs?: number;
+  clientName?: string;
+  tls?: { rejectUnauthorized?: boolean; ca?: string | Buffer | (string | Buffer)[]; servername?: string; minVersion?: string };
+}
+export function smtpTransport(options: SmtpOptions): Transport & { verify(): Promise<true> };
+export function resendTransport(options: { apiKey: string; apiUrl?: string; fetch?: typeof fetch; timeoutMs?: number }): Transport;
+export function memoryTransport(): Transport & {
+  sent: (PreparedMessage & { links: string[] })[];
+  last(): (PreparedMessage & { links: string[] }) | undefined;
+  to(address: string): (PreparedMessage & { links: string[] }) | undefined;
+  clear(): void;
+};
+export function failoverTransport(transports: Transport[]): Transport & { verify(): Promise<boolean> };
+
+export interface MailerOptions extends Partial<MessageInput> {
+  transport: Transport;
+  /** Extra tries for temporary failures. Default 2. */
+  retries?: number;
+  retryDelayMs?: number;
+  /** Every mail goes here instead (staging); the real recipients are noted in the subject. */
+  redirectAllTo?: AddressesInput;
+  /** Only these recipient domains may get mail. */
+  allowDomains?: string[];
+  onSent?: (info: SendResult & { to: string[]; subject: string }) => void;
+  onError?: (error: MailError, info: { to: string[]; subject: string }) => void;
+}
+export function createMailer(options: MailerOptions): {
+  send(message: MessageInput): Promise<SendResult>;
+  verify(): Promise<unknown>;
+  transport: Transport;
+};

package/src/index.js

@@ -0,0 +1,14 @@
+import { MailError } from "./errors.js";
+import { encodeWords, formatAddress, isEmail, normalizeAddress, parseAddress, parseAddressList } from "./address.js";
+import { prepareMessage, quotedPrintable } from "./message.js";
+import { escapeHtml, extractLinks, htmlToText, wrapText } from "./text.js";
+import { block, email, escapeMarkup } from "./template.js";
+import { smtpTransport } from "./smtp.js";
+import { failoverTransport, memoryTransport, resendTransport } from "./transports.js";
+import { createMailer } from "./mailer.js";
+import { lintEmail } from "./lint.js";
+import { preview } from "./preview.js";
+
+export { MailError, encodeWords, formatAddress, isEmail, normalizeAddress, parseAddress, parseAddressList };
+export { prepareMessage, quotedPrintable, escapeHtml, extractLinks, htmlToText, wrapText };
+export { block, email, escapeMarkup, smtpTransport, failoverTransport, memoryTransport, resendTransport, createMailer, lintEmail, preview };

package/src/lint.js

@@ -0,0 +1,31 @@
+import { prepareMessage } from "./message.js";
+import { extractLinks } from "./text.js";
+
+/**
+ * Looks at a mail the way a spam filter and an inbox would, and returns a list of `{ level, message }` hints.
+ * It is advice, not a guarantee of delivery.
+ */
+export function lintEmail(input) {
+  const m = input.raw ? input : prepareMessage({ from: "lint@example.com", to: "lint@example.com", ...input });
+  const out = [];
+  const warn = (message) => out.push({ level: "warning", message });
+  const info = (message) => out.push({ level: "info", message });
+  if (m.subject.length > 78) warn(`Subject is ${m.subject.length} characters; inboxes cut it off around 60-78.`);
+  if (m.subject.length > 3 && m.subject === m.subject.toUpperCase() && /[A-Z]/.test(m.subject)) warn("Subject is ALL CAPS, which spam filters dislike.");
+  if (/!{2,}/.test(m.subject)) warn("Subject has repeated exclamation marks.");
+  if (m.html !== undefined) {
+    const size = Buffer.byteLength(m.html);
+    if (size > 100_000) warn(`HTML is ${Math.round(size / 1000)} KB; Gmail cuts messages off at about 102 KB.`);
+    if (/<img\b/i.test(m.html) && !/<img\b[^>]*\balt=/i.test(m.html)) warn("An image has no alt text.");
+    if (/<script\b|\son\w+\s*=|javascript:/i.test(m.html)) warn("HTML contains script or event handlers; mail clients strip them.");
+    if (/<link\b[^>]*stylesheet|@import/i.test(m.html)) warn("External stylesheets are ignored by most mail clients; use inline styles.");
+    const textLength = m.text.replace(/\s+/g, "").length;
+    if (textLength < 40 && /<img\b/i.test(m.html)) warn("Almost only images; add real text, it helps delivery and accessibility.");
+  }
+  const links = [...new Set([...extractLinks(m.html ?? ""), ...extractLinks(m.text)])];
+  if (links.some((l) => l.startsWith("http://"))) warn("Contains an http:// link; use https://.");
+  if (links.length > 10) info(`Contains ${links.length} links; fewer is safer for delivery.`);
+  const hasUnsub = Object.keys(m.headers).some((h) => h.toLowerCase() === "list-unsubscribe");
+  if (!hasUnsub && !/^auto-generated$/i.test(m.headers["Auto-Submitted"] ?? "")) info("No List-Unsubscribe header; add one if this is not a transactional mail.");
+  return out;
+}

package/src/mailer.js

@@ -0,0 +1,66 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { parseAddress, parseAddressList } from "./address.js";
+import { MailError } from "./errors.js";
+import { prepareMessage } from "./message.js";
+
+const mask = (address) => address.replace(/^(.).*(@.*)$/, "$1***$2");
+
+/**
+ * The one object an app uses: `mailer.send({ to, subject, html })` checks the message, sends it, retries
+ * temporary failures with a pause, and can keep staging or test systems from mailing real people.
+ *
+ * @param {object} options
+ * @param {{ send(message): Promise<object> }} options.transport  smtpTransport, resendTransport, memoryTransport, failoverTransport
+ * @param {string|{name,address}} options.from  default sender
+ * @param {string|string[]} [options.redirectAllTo]  every mail goes to these addresses instead (staging); the real recipients are put in the subject
+ * @param {string[]} [options.allowDomains]  only these recipient domains may receive mail; others fail before sending
+ */
+export function createMailer(options = {}) {
+  const { transport, retries = 2, retryDelayMs = 500, onSent, onError, redirectAllTo, allowDomains, ...defaults } = options;
+  if (!transport || typeof transport.send !== "function") throw new MailError("createMailer needs a transport", { code: "invalid_config" });
+  const redirect = redirectAllTo ? parseAddressList(redirectAllTo) : null;
+  const allowed = allowDomains ? new Set(allowDomains.map((d) => String(d).toLowerCase())) : null;
+  if (defaults.from !== undefined) parseAddress(defaults.from);
+
+  const guard = (message) => {
+    if (!allowed) return;
+    const blocked = message.envelope.to.filter((a) => !allowed.has(a.split("@")[1]));
+    if (blocked.length) throw new MailError(`Recipient domain not allowed: ${blocked.map(mask).join(", ")}`, { code: "recipient_not_allowed" });
+  };
+
+  async function send(input) {
+    let message = prepareMessage(input, defaults);
+    guard(message);
+    if (redirect) {
+      const original = message.envelope.to.map(mask).join(", ");
+      message = prepareMessage({ ...input, to: redirect, cc: undefined, bcc: undefined, subject: `[to: ${original}] ${message.subject}` }, defaults);
+    }
+    let attempt = 0;
+    for (;;) {
+      attempt++;
+      try {
+        const result = await transport.send(message);
+        const done = { ...result, attempts: attempt, transport: result.transport ?? transport.name };
+        try { onSent?.({ ...done, to: message.envelope.to.map(mask), subject: message.subject }); } catch { /* a logging hook must not break sending */ }
+        return done;
+      } catch (error) {
+        const wrapped = error instanceof MailError ? error : new MailError(`Sending failed: ${error?.message ?? error}`, { code: "send_failed", cause: error });
+        if (wrapped.retryable && attempt <= retries) {
+          await sleep(Math.round(retryDelayMs * 2 ** (attempt - 1) * (0.75 + Math.random() * 0.5)));
+          continue;
+        }
+        wrapped.attempts = attempt;
+        try { onError?.(wrapped, { to: message.envelope.to.map(mask), subject: message.subject }); } catch { /* same */ }
+        throw wrapped;
+      }
+    }
+  }
+
+  return {
+    send,
+    /** Checks the transport settings (connects and logs in for SMTP). Call it once at startup. */
+    verify: async () => (typeof transport.verify === "function" ? transport.verify() : true),
+    transport,
+  };
+}

package/src/message.js

@@ -0,0 +1,190 @@
+import { randomBytes } from "node:crypto";
+
+import { encodeWords, formatAddress, formatAddressList, parseAddress, parseAddressList } from "./address.js";
+import { MailError } from "./errors.js";
+import { htmlToText } from "./text.js";
+
+const RESERVED = new Set(["from", "to", "cc", "bcc", "subject", "date", "message-id", "mime-version", "content-type", "content-transfer-encoding", "reply-to", "sender", "return-path"]);
+const MAX_RECIPIENTS = 50;
+
+const fail = (message, code = "invalid_message") => new MailError(message, { code });
+
+/** Quoted-printable (RFC 2045) of a text: lines of at most 76 characters, CRLF line breaks. */
+export function quotedPrintable(text) {
+  const bytes = Buffer.from(String(text).replace(/\r\n?|\n/g, "\n"), "utf8");
+  const lines = [];
+  let line = "";
+  let tokens = [];
+  const flush = () => {
+    if (tokens.length) {
+      const last = tokens[tokens.length - 1];
+      if (last === " " || last === "\t") tokens[tokens.length - 1] = "=" + last.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0");
+    }
+    let width = 0;
+    line = "";
+    for (const t of tokens) {
+      if (width + t.length > 75) {
+        lines.push(line + "=");
+        line = "";
+        width = 0;
+      }
+      line += t;
+      width += t.length;
+    }
+    lines.push(line);
+    tokens = [];
+  };
+  for (const b of bytes) {
+    if (b === 10) flush();
+    else if ((b >= 33 && b <= 126 && b !== 61) || b === 32 || b === 9) tokens.push(String.fromCharCode(b));
+    else tokens.push("=" + b.toString(16).toUpperCase().padStart(2, "0"));
+  }
+  flush();
+  return lines.join("\r\n");
+}
+
+const base64Lines = (buffer) => (buffer.toString("base64").match(/.{1,76}/g) ?? []).join("\r\n");
+const boundary = () => `=_ss_${randomBytes(12).toString("hex")}`;
+const needsEncoding = (name) => !/^[\x20-\x7e]*$/.test(name);
+const quote = (value) => `"${value.replace(/(["\\])/g, "\\$1")}"`;
+
+const extended = (name) => `UTF-8''${encodeURIComponent(name).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+// ASCII names are plain quoted parameters; others use RFC 2231 (`name*=UTF-8''...`), which Gmail, Outlook, Apple Mail and Thunderbird read.
+const param = (key, name) => (needsEncoding(name) ? `${key}*=${extended(name)}` : `${key}=${quote(name)}`);
+
+function textPart(contentType, body) {
+  return `Content-Type: ${contentType}; charset=utf-8\r\nContent-Transfer-Encoding: quoted-printable\r\n\r\n${quotedPrintable(body)}\r\n`;
+}
+
+function multipart(type, parts) {
+  const b = boundary();
+  return { header: `Content-Type: multipart/${type}; boundary="${b}"`, body: `${parts.map((p) => `--${b}\r\n${p}`).join("")}--${b}--\r\n` };
+}
+
+// A child part is a string that starts with its own headers (it is already a full MIME entity).
+const entity = (m) => `${m.header}\r\n\r\n${m.body}`;
+
+function attachmentPart(a) {
+  const disposition = a.cid ? "inline" : "attachment";
+  return (
+    `Content-Type: ${a.contentType}; ${param("name", a.filename)}\r\n` +
+    `Content-Transfer-Encoding: base64\r\n` +
+    `Content-Disposition: ${disposition}; ${param("filename", a.filename)}\r\n` +
+    (a.cid ? `Content-ID: <${a.cid}>\r\n` : "") +
+    `\r\n${base64Lines(a.content)}\r\n`
+  );
+}
+
+function checkHeaderValue(name, value) {
+  if (typeof value !== "string" || /[\r\n\0]/.test(value)) throw fail(`Header ${name} must be a single line of text`, "invalid_header");
+}
+
+function normalizeAttachment(a, index) {
+  if (!a || typeof a !== "object") throw fail(`attachments[${index}] must be an object`);
+  const content = typeof a.content === "string" ? Buffer.from(a.content, a.encoding === "base64" ? "base64" : "utf8") : a.content;
+  if (!Buffer.isBuffer(content) && !(content instanceof Uint8Array)) throw fail(`attachments[${index}].content must be a Buffer or string`);
+  const filename = String(a.filename ?? "").replace(/[\r\n\0/\\]/g, "_").trim();
+  if (!filename) throw fail(`attachments[${index}].filename is required`);
+  const contentType = String(a.contentType ?? "application/octet-stream");
+  if (!/^[\w.+-]+\/[\w.+-]+$/.test(contentType)) throw fail(`attachments[${index}].contentType is not valid`);
+  const cid = a.cid === undefined ? undefined : String(a.cid);
+  if (cid !== undefined && !/^[\w.@+-]{1,200}$/.test(cid)) throw fail(`attachments[${index}].cid is not valid`);
+  return { filename, content: Buffer.from(content), contentType, cid };
+}
+
+/**
+ * Checks and normalizes a message. The result has everything a transport needs, and `raw` (a Buffer with the
+ * complete RFC 5322 message) is built on first use.
+ */
+export function prepareMessage(input, defaults = {}) {
+  if (!input || typeof input !== "object") throw fail("A message must be an object");
+  const merged = { ...defaults, ...input, headers: { ...defaults.headers, ...input.headers } };
+  const from = parseAddress(merged.from ?? (() => { throw fail("from is required", "missing_from"); })());
+  const to = parseAddressList(merged.to);
+  const cc = parseAddressList(merged.cc);
+  const bcc = parseAddressList(merged.bcc);
+  const replyTo = parseAddressList(merged.replyTo);
+  const unique = new Map();
+  for (const a of [...to, ...cc, ...bcc]) if (!unique.has(a.address.toLowerCase())) unique.set(a.address.toLowerCase(), a.address);
+  const total = new Set(unique.values());
+  if (!total.size) throw fail("At least one recipient (to, cc or bcc) is required", "no_recipients");
+  if (total.size > (merged.maxRecipients ?? MAX_RECIPIENTS)) throw fail(`Too many recipients (${total.size}); send in smaller batches or raise maxRecipients`, "too_many_recipients");
+
+  const subject = String(merged.subject ?? "").replace(/[\t ]+/g, " ").trim();
+  if (!subject) throw fail("subject is required", "missing_subject");
+  if (/[\r\n\0]/.test(subject)) throw fail("subject may not contain line breaks", "invalid_header");
+
+  let html = merged.html === undefined ? undefined : String(merged.html);
+  let text = merged.text === undefined ? undefined : String(merged.text);
+  if (html === undefined && text === undefined) throw fail("Give the message a text or html body", "empty_body");
+  if (text === undefined) text = htmlToText(html);
+
+  const attachments = (merged.attachments ?? []).map(normalizeAttachment);
+  const headers = {};
+  for (const [name, value] of Object.entries(merged.headers)) {
+    if (value === undefined || value === null) continue;
+    if (!/^[A-Za-z0-9-]{1,60}$/.test(name)) throw fail(`Header name not allowed: ${name.slice(0, 40)}`, "invalid_header");
+    if (RESERVED.has(name.toLowerCase())) throw fail(`Set ${name} with its own option, not in headers`, "invalid_header");
+    checkHeaderValue(name, String(value));
+    headers[name] = String(value);
+  }
+  if (merged.autoSubmitted !== false && !Object.keys(headers).some((n) => n.toLowerCase() === "auto-submitted")) headers["Auto-Submitted"] = "auto-generated";
+  if (merged.unsubscribe) {
+    const { url, mailto } = merged.unsubscribe;
+    const items = [];
+    if (url) {
+      if (!/^https:\/\/[^\s<>]+$/.test(url)) throw fail("unsubscribe.url must be an https URL", "invalid_header");
+      items.push(`<${url}>`);
+      headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+    }
+    if (mailto) items.push(`<mailto:${parseAddress(mailto).address}>`);
+    if (!items.length) throw fail("unsubscribe needs a url or mailto", "invalid_header");
+    headers["List-Unsubscribe"] = items.join(", ");
+  }
+
+  const messageId = merged.messageId ?? `<${randomBytes(16).toString("hex")}@${from.address.split("@")[1]}>`;
+  if (!/^<[^<>\s@]+@[^<>\s@]+>$/.test(messageId)) throw fail("messageId must look like <id@domain>", "invalid_header");
+  const date = merged.date instanceof Date ? merged.date : new Date();
+  const envelopeFrom = merged.envelopeFrom ? parseAddress(merged.envelopeFrom).address : from.address;
+  const envelopeTo = [...total];
+
+  const message = {
+    from, to, cc, bcc, replyTo, subject, html, text, headers, attachments, messageId, date,
+    envelope: { from: envelopeFrom, to: envelopeTo },
+  };
+  let raw;
+  Object.defineProperty(message, "raw", { enumerable: false, get: () => (raw ??= buildRaw(message)) });
+  return message;
+}
+
+function buildRaw(m) {
+  const head = [];
+  head.push(`From: ${formatAddress(m.from)}`);
+  if (m.to.length) head.push(`To: ${formatAddressList(m.to)}`);
+  if (m.cc.length) head.push(`Cc: ${formatAddressList(m.cc)}`);
+  if (m.replyTo.length) head.push(`Reply-To: ${formatAddressList(m.replyTo)}`);
+  head.push(`Subject: ${encodeWords(m.subject)}`);
+  head.push(`Date: ${m.date.toUTCString().replace("GMT", "+0000")}`);
+  head.push(`Message-ID: ${m.messageId}`);
+  head.push("MIME-Version: 1.0");
+  for (const [name, value] of Object.entries(m.headers)) head.push(`${name}: ${encodeWords(value)}`);
+
+  const inline = m.attachments.filter((a) => a.cid);
+  const regular = m.attachments.filter((a) => !a.cid);
+  let body;
+  if (m.html === undefined) body = { header: null, text: m.text };
+  else {
+    const htmlEntity = inline.length
+      ? multipart("related", [textPart("text/html", m.html), ...inline.map(attachmentPart)])
+      : null;
+    const htmlPart = htmlEntity ? entity(htmlEntity) + "\r\n" : textPart("text/html", m.html);
+    body = multipart("alternative", [textPart("text/plain", m.text), htmlPart]);
+  }
+  let top;
+  if (regular.length) {
+    const first = body.header ? entity(body) + "\r\n" : textPart("text/plain", m.text);
+    top = multipart("mixed", [first, ...regular.map(attachmentPart)]);
+  } else if (body.header) top = body;
+  else top = { header: "Content-Type: text/plain; charset=utf-8\r\nContent-Transfer-Encoding: quoted-printable", body: `${quotedPrintable(m.text)}\r\n` };
+  return Buffer.from(`${head.join("\r\n")}\r\n${top.header}\r\n\r\n${top.body}`, "latin1");
+}

package/src/preview.js

@@ -0,0 +1,12 @@
+import { escapeHtml } from "./text.js";
+
+/**
+ * One HTML page that shows a mail the way you want to review it: subject, the rendered mail (narrow and wide) and
+ * the plain-text version. Write it to a file and open it in a browser: `writeFileSync("mail.html", preview(mail))`.
+ */
+export function preview(mail) {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Preview: ${escapeHtml(mail.subject)}</title>
+<style>body{font:15px system-ui,sans-serif;margin:0;padding:24px;background:#e7eaee;color:#1f2933}h1{font-size:18px;margin:0 0 4px}.meta{color:#6b7785;margin:0 0 20px}.row{display:flex;gap:20px;flex-wrap:wrap;align-items:flex-start}iframe{border:0;background:#fff;box-shadow:0 1px 4px #0003;height:760px}pre{background:#fff;padding:16px;white-space:pre-wrap;max-width:560px;box-shadow:0 1px 4px #0003}</style></head><body>
+<h1>${escapeHtml(mail.subject)}</h1><p class="meta">HTML (wide and phone width) and the text version</p>
+<div class="row"><iframe style="width:680px" srcdoc="${escapeHtml(mail.html ?? "")}"></iframe><iframe style="width:380px" srcdoc="${escapeHtml(mail.html ?? "")}"></iframe><pre>${escapeHtml(mail.text)}</pre></div></body></html>`;
+}