@benclmnt/postmock 0.0.1

package/dist/src/http/routes.js

@@ -0,0 +1,64 @@
+/**
+ * Method + path patterns (`/templates/:idOrAlias`). Literal segments match without case and a
+ * trailing slash is ignored (docs/08 R2). A literal beats a param at the same position, so
+ * `PUT /templates/push` wins over `PUT /templates/:idOrAlias` (docs/08 §2.5).
+ */
+export class RouteTable {
+    entries = [];
+    add(route) {
+        const segments = parsePattern(route.path);
+        const shape = shapeOf(segments);
+        const clash = this.entries.find((e) => e.route.method === route.method && shapeOf(e.segments) === shape);
+        if (clash)
+            throw new Error(`route ${route.method} ${route.path} clashes with ${clash.route.path}`);
+        this.entries.push({ route, segments });
+    }
+    match(method, pathname) {
+        const parts = pathSegments(pathname);
+        if (parts === undefined)
+            return undefined;
+        let best;
+        for (const { route, segments } of this.entries) {
+            if (route.method !== method.toUpperCase() || segments.length !== parts.length)
+                continue;
+            const params = {};
+            const ok = segments.every((segment, i) => {
+                const part = parts[i];
+                if ("param" in segment)
+                    params[segment.param] = part;
+                return "param" in segment || segment.literal === part.toLowerCase();
+            });
+            const rank = segments.map((s) => ("literal" in s ? "0" : "1")).join("");
+            if (ok && (best === undefined || rank < best.rank))
+                best = { route, params, rank };
+        }
+        return best && { route: best.route, params: best.params };
+    }
+}
+/**
+ * Decoded segments of a request path. One trailing slash is ignored (docs/08 R2); any other empty
+ * segment (`//email`) or a malformed percent-escape matches no route.
+ */
+function pathSegments(pathname) {
+    const parts = pathname.replace(/^\//, "").replace(/\/$/, "").split("/");
+    if (parts.some((p) => p === ""))
+        return undefined;
+    try {
+        return parts.map(decodeURIComponent);
+    }
+    catch {
+        return undefined;
+    }
+}
+function parsePattern(path) {
+    return path
+        .split("/")
+        .filter(Boolean)
+        .map((s) => (s.startsWith(":") ? { param: s.slice(1) } : { literal: s.toLowerCase() }));
+}
+const shapeOf = (segments) => segments.map((s) => ("literal" in s ? s.literal : ":")).join("/");
+export const apiRoutes = new RouteTable();
+/** Registers a Postmark API route. Each `src/api/<group>/routes.ts` calls it at import. */
+export function defineRoute(route) {
+    apiRoutes.add(route);
+}

package/dist/src/inbound/deliver.d.ts

@@ -0,0 +1,9 @@
+import type { Runtime } from "../runtime.ts";
+import type { InboundMessage } from "../state/types.ts";
+/**
+ * POSTs an inbound message to the server's `InboundHookUrl` (docs/05 §3.6, §4.1) and tracks its
+ * status: `Processed` on success, `Scheduled` while a retry waits, `Failed` after a 403 or the last
+ * retry. A server without a hook URL processes the message at once. The status names follow the
+ * inbound search filter (refs/api_messages-api.md:315); the mapping is INFERRED.
+ */
+export declare function deliverInbound(runtime: Runtime, message: InboundMessage): Promise<void>;

package/dist/src/inbound/deliver.js

@@ -0,0 +1,34 @@
+import { deliver, INBOUND } from "../webhooks/deliver.js";
+import { inboundPayload } from "../webhooks/payloads.js";
+/**
+ * POSTs an inbound message to the server's `InboundHookUrl` (docs/05 §3.6, §4.1) and tracks its
+ * status: `Processed` on success, `Scheduled` while a retry waits, `Failed` after a 403 or the last
+ * retry. A server without a hook URL processes the message at once. The status names follow the
+ * inbound search filter (refs/api_messages-api.md:315); the mapping is INFERRED.
+ */
+export async function deliverInbound(runtime, message) {
+    const server = runtime.store.state.servers.get(message.ServerID);
+    // Like outbound events, an event of a server that no longer exists goes nowhere.
+    if (server === undefined)
+        return;
+    if (server.InboundHookUrl === "") {
+        message.Status = "Processed";
+        return;
+    }
+    await deliver(runtime, {
+        target: {
+            serverId: server.ID,
+            hook: { kind: "server", field: "InboundHookUrl" },
+            url: server.InboundHookUrl,
+            httpAuth: null,
+            headers: [],
+        },
+        recordType: "Inbound",
+        payload: inboundPayload(message, server.RawEmailEnabled),
+        policy: INBOUND,
+        onResult: (result) => {
+            message.Status =
+                result === "success" ? "Processed" : result === "retry" ? "Scheduled" : "Failed";
+        },
+    });
+}

package/dist/src/inbound/parse.d.ts

@@ -0,0 +1,21 @@
+import type { Header, InboundAddress, InboundAttachment } from "../state/types.ts";
+/** What inbound processing reads from a received MIME message (docs/05 §4.2). */
+export interface ParsedMail {
+    from: InboundAddress;
+    to: InboundAddress[];
+    cc: InboundAddress[];
+    replyTo: string;
+    subject: string;
+    /** The `Date` header as the sender wrote it. */
+    date: string;
+    textBody: string;
+    htmlBody: string;
+    strippedTextReply: string;
+    headers: Header[];
+    attachments: InboundAttachment[];
+}
+/** Text after `+` in the local part, or `""` (docs/05 §4.2). */
+export declare const mailboxHash: (email: string) => string;
+/** The legacy string form: `"Name" <email>` or a bare `email`, comma-separated (docs/05 §4.2). */
+export declare const legacyList: (list: InboundAddress[]) => string;
+export declare function parseMime(mime: string): Promise<ParsedMail>;

package/dist/src/inbound/parse.js

@@ -0,0 +1,71 @@
+import { simpleParser } from "mailparser";
+/** Text after `+` in the local part, or `""` (docs/05 §4.2). */
+export const mailboxHash = (email) => {
+    const local = email.slice(0, email.lastIndexOf("@"));
+    const plus = local.indexOf("+");
+    return plus === -1 ? "" : local.slice(plus + 1);
+};
+const full = (a) => ({
+    Email: a.address ?? "",
+    Name: a.name,
+    MailboxHash: mailboxHash(a.address ?? ""),
+});
+const addresses = (field) => (Array.isArray(field) ? field : field === undefined ? [] : [field])
+    .flatMap((o) => o.value)
+    .flatMap((a) => a.group ?? [a])
+    .map(full);
+/** The legacy string form: `"Name" <email>` or a bare `email`, comma-separated (docs/05 §4.2). */
+export const legacyList = (list) => list.map((a) => (a.Name === "" ? a.Email : `"${a.Name}" <${a.Email}>`)).join(", ");
+// The doc example `Headers` holds MIME-Version, Message-ID and trace headers, but not the headers
+// that have their own field (refs/user-guide_inbound_parse-an-email.md:113-146; INFERRED).
+const OWN_FIELD = new Set([
+    "from",
+    "to",
+    "cc",
+    "bcc",
+    "reply-to",
+    "subject",
+    "date",
+    "content-type",
+    "content-transfer-encoding",
+]);
+// A reply's quoted part starts at an attribution line or the first quoted line (INFERRED).
+const QUOTE_START = /^(On .+ wrote:|>)/m;
+export async function parseMime(mime) {
+    const mail = await simpleParser(mime, {
+        skipHtmlToText: true,
+        skipTextToHtml: true,
+        skipImageLinks: true,
+        skipTextLinks: true,
+    });
+    const text = mail.text ?? "";
+    const isReply = mail.headers.has("in-reply-to") || mail.headers.has("references");
+    const quote = QUOTE_START.exec(text);
+    const lineOf = (key) => mail.headerLines.find((h) => h.key === key)?.line;
+    const headerValue = (line) => line
+        .slice(line.indexOf(":") + 1)
+        .replace(/\r?\n/g, "")
+        .trim();
+    return {
+        from: addresses(mail.from)[0] ?? { Email: "", Name: "", MailboxHash: "" },
+        to: addresses(mail.to),
+        cc: addresses(mail.cc),
+        replyTo: legacyList(addresses(mail.replyTo)),
+        subject: mail.subject ?? "",
+        date: headerValue(lineOf("date") ?? ":"),
+        textBody: text,
+        htmlBody: mail.html === false ? "" : mail.html,
+        // docs/05 §4.2: only a reply with a plain part gets one.
+        strippedTextReply: isReply ? (quote === null ? text : text.slice(0, quote.index)).trim() : "",
+        headers: mail.headerLines
+            .filter((h) => !OWN_FIELD.has(h.key))
+            .map((h) => ({ Name: h.line.slice(0, h.line.indexOf(":")), Value: headerValue(h.line) })),
+        attachments: mail.attachments.map((a) => ({
+            Name: a.filename ?? "",
+            Content: a.content.toString("base64"),
+            ContentType: a.contentType,
+            ContentLength: a.content.length,
+            ContentID: a.cid ?? "",
+        })),
+    };
+}

package/dist/src/inbound/receive.d.ts

@@ -0,0 +1,17 @@
+import type { Runtime } from "../runtime.ts";
+import type { InboundMessage } from "../state/types.ts";
+/** A message as it reaches Postmark's MX: its source, the SMTP envelope and SpamAssassin's verdict. */
+export interface ReceivedMail {
+    mime: string;
+    /** RCPT TO addresses; a recipient outside the headers is a Bcc. */
+    rcptTo: string[];
+    spamScore: number;
+    spamTests: string[];
+}
+/**
+ * Receives one mail: one inbound message per server it reaches, with that server's first inbound
+ * recipient as `OriginalRecipient` (INFERRED). A sender that matches an inbound rule, or a spam score
+ * above a set `InboundSpamThreshold`, blocks the message (docs/05 §4.1). Emits `inboundReceived` per
+ * message; the webhooks plugin posts every message that is not blocked.
+ */
+export declare function receiveInbound(runtime: Runtime, mail: ReceivedMail): Promise<InboundMessage[]>;

package/dist/src/inbound/receive.js

@@ -0,0 +1,89 @@
+import { newMessageId } from "../state/ids.js";
+import { legacyList, mailboxHash, parseMime } from "./parse.js";
+/** Whether `email` is an inbound address of `server`: its hash address or its inbound domain. */
+function isInboundAddress(server, email) {
+    const at = email.lastIndexOf("@");
+    const local = email.slice(0, at).toLowerCase().split("+")[0];
+    const domain = email.slice(at + 1).toLowerCase();
+    return ((domain === "inbound.postmarkapp.com" && local === server.InboundHash.toLowerCase()) ||
+        (server.InboundDomain !== "" && domain === server.InboundDomain.toLowerCase()));
+}
+/**
+ * Receives one mail: one inbound message per server it reaches, with that server's first inbound
+ * recipient as `OriginalRecipient` (INFERRED). A sender that matches an inbound rule, or a spam score
+ * above a set `InboundSpamThreshold`, blocks the message (docs/05 §4.1). Emits `inboundReceived` per
+ * message; the webhooks plugin posts every message that is not blocked.
+ */
+export async function receiveInbound(runtime, mail) {
+    const { state } = runtime.store;
+    const parsed = await parseMime(mail.mime);
+    const now = runtime.clock.now();
+    const spamHeaders = [
+        { Name: "X-Spam-Status", Value: mail.spamScore > 5 ? "Yes" : "No" },
+        { Name: "X-Spam-Score", Value: String(mail.spamScore) },
+        { Name: "X-Spam-Tests", Value: mail.spamTests.join(",") },
+    ];
+    const messages = [];
+    for (const server of state.servers.values()) {
+        const recipient = mail.rcptTo.find((r) => isInboundAddress(server, r));
+        const stream = [...state.streams.values()].find((s) => s.ServerID === server.ID && s.MessageStreamType === "Inbound");
+        if (recipient === undefined || stream === undefined)
+            continue;
+        const inHeaders = [...parsed.to, ...parsed.cc].some((a) => a.Email.toLowerCase() === recipient.toLowerCase());
+        // docs/05 §4.2 Bcc rules: the inbound address shows as Bcc only when no To or Cc names it.
+        const bcc = inHeaders
+            ? []
+            : [{ Email: recipient, Name: "", MailboxHash: mailboxHash(recipient) }];
+        const blockedReason = blockReason(runtime, server, parsed.from.Email, mail.spamScore);
+        const message = {
+            MessageID: newMessageId(),
+            ServerID: server.ID,
+            MessageStream: stream.ID,
+            From: parsed.from.Email,
+            FromName: parsed.from.Name,
+            FromFull: parsed.from,
+            To: legacyList(parsed.to),
+            ToFull: parsed.to,
+            Cc: legacyList(parsed.cc),
+            CcFull: parsed.cc,
+            Bcc: legacyList(bcc),
+            BccFull: bcc,
+            OriginalRecipient: recipient,
+            ReplyTo: parsed.replyTo,
+            Subject: parsed.subject,
+            MailboxHash: mailboxHash(recipient),
+            Date: parsed.date,
+            TextBody: parsed.textBody,
+            HtmlBody: parsed.htmlBody,
+            StrippedTextReply: parsed.strippedTextReply,
+            Tag: "",
+            Headers: [...spamHeaders, ...parsed.headers],
+            Attachments: parsed.attachments,
+            Status: blockedReason === null ? "Queued" : "Blocked",
+            BlockedReason: blockedReason,
+            ReceivedAt: now,
+            rawEmail: mail.mime,
+        };
+        state.inbound.set(message.MessageID, message);
+        messages.push(message);
+    }
+    for (const message of messages)
+        await runtime.events.emit("inboundReceived", { message });
+    return messages;
+}
+/** Why a message is blocked, or null. The reason texts are INFERRED. */
+function blockReason(runtime, server, from, spamScore) {
+    const sender = from.toLowerCase();
+    const rule = [...runtime.store.state.inboundRules.values()].find((r) => {
+        const value = r.Rule.toLowerCase();
+        return (r.ServerID === server.ID &&
+            (value.includes("@") ? sender === value : sender.slice(sender.lastIndexOf("@") + 1) === value));
+    });
+    if (rule !== undefined)
+        return `Blocked by inbound rule '${rule.Rule}'.`;
+    // A threshold of 0 blocks nothing (INFERRED).
+    if (server.InboundSpamThreshold > 0 && spamScore > server.InboundSpamThreshold) {
+        return `Spam score ${spamScore} is above the threshold ${server.InboundSpamThreshold}.`;
+    }
+    return null;
+}

package/dist/src/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/main.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { applyFlags, configFromEnv, USAGE } from "./config.js";
+import { startPostmock } from "./server.js";
+if (applyFlags(process.argv.slice(2), process.env) === "help") {
+    console.log(USAGE);
+    process.exit(0);
+}
+const config = configFromEnv(process.env);
+const running = await startPostmock(config);
+const urls = Object.entries(running.listeners).map(([name, url]) => `${name}=${url}`);
+console.log(`postmock ${urls.join(" ")} seed=${config.seed}`);
+for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, () => void running.close().then(() => process.exit(0)));
+}

package/dist/src/mime/compose.d.ts

@@ -0,0 +1,33 @@
+/** An address as the control API takes it: `a@example.com` or `{email, name}`. */
+export type MailAddress = string | {
+    email: string;
+    name?: string | undefined;
+};
+/** A message a real sender could write (CONTROL-API.md `POST /control/inbound`). */
+export interface MailFields {
+    from: MailAddress;
+    to: MailAddress[];
+    cc: MailAddress[];
+    replyTo?: MailAddress | undefined;
+    subject: string;
+    text?: string | undefined;
+    html?: string | undefined;
+    headers: Array<{
+        name: string;
+        value: string;
+    }>;
+    attachments: Array<{
+        name: string;
+        /** Base64. */
+        content: string;
+        contentType: string;
+        contentId?: string | undefined;
+    }>;
+}
+/** RFC 5322 date in UTC: `Thu, 05 Nov 2026 21:33:54 +0000`. */
+export declare const rfc5322Date: (d: Date) => string;
+/**
+ * Writes the MIME source a mail client would send for these fields. Inbound processing then parses
+ * it like any received mail, so both control API input forms take one path.
+ */
+export declare function composeMime(fields: MailFields, now: Date): string;

package/dist/src/mime/compose.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+const ascii = (text) => /^[\x20-\x7e]*$/.test(text);
+/** RFC 2047 encoded word for non-ASCII header text. */
+const word = (text) => ascii(text) ? text : `=?UTF-8?B?${Buffer.from(text).toString("base64")}?=`;
+const address = (a) => {
+    const { email, name } = typeof a === "string" ? { email: a, name: undefined } : a;
+    if (name === undefined || name === "")
+        return email;
+    return ascii(name)
+        ? `"${name.replace(/["\\]/g, "\\$&")}" <${email}>`
+        : `${word(name)} <${email}>`;
+};
+const base64Lines = (content) => (Buffer.isBuffer(content) ? content : Buffer.from(content))
+    .toString("base64")
+    .replace(/.{76}/g, "$&\r\n");
+const DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+const two = (n) => String(n).padStart(2, "0");
+/** RFC 5322 date in UTC: `Thu, 05 Nov 2026 21:33:54 +0000`. */
+export const rfc5322Date = (d) => `${DAYS[d.getUTCDay()]}, ${two(d.getUTCDate())} ${MONTHS[d.getUTCMonth()]} ${d.getUTCFullYear()} ` +
+    `${two(d.getUTCHours())}:${two(d.getUTCMinutes())}:${two(d.getUTCSeconds())} +0000`;
+/**
+ * Writes the MIME source a mail client would send for these fields. Inbound processing then parses
+ * it like any received mail, so both control API input forms take one path.
+ */
+export function composeMime(fields, now) {
+    const boundary = () => `postmock-${randomUUID()}`;
+    const textPart = (type, body) => `Content-Type: ${type}; charset=utf-8\r\nContent-Transfer-Encoding: base64\r\n\r\n${base64Lines(body)}\r\n`;
+    const multipart = (subtype, parts) => {
+        const b = boundary();
+        return `Content-Type: multipart/${subtype}; boundary="${b}"\r\n\r\n${parts.map((p) => `--${b}\r\n${p}`).join("")}--${b}--\r\n`;
+    };
+    const bodies = [
+        ...(fields.text !== undefined ? [textPart("text/plain", fields.text)] : []),
+        ...(fields.html !== undefined ? [textPart("text/html", fields.html)] : []),
+    ];
+    const content = bodies.length === 2
+        ? multipart("alternative", bodies)
+        : (bodies[0] ?? textPart("text/plain", ""));
+    const attachments = fields.attachments.map((a) => `Content-Type: ${a.contentType}; name="${word(a.name)}"\r\n` +
+        `Content-Disposition: ${a.contentId === undefined ? "attachment" : "inline"}; filename="${word(a.name)}"\r\n` +
+        (a.contentId === undefined ? "" : `Content-ID: <${a.contentId}>\r\n`) +
+        `Content-Transfer-Encoding: base64\r\n\r\n${base64Lines(Buffer.from(a.content, "base64"))}\r\n`);
+    const given = (name) => fields.headers.some((h) => h.name.toLowerCase() === name);
+    const headers = [
+        `From: ${address(fields.from)}`,
+        ...(fields.to.length > 0 ? [`To: ${fields.to.map(address).join(", ")}`] : []),
+        ...(fields.cc.length > 0 ? [`Cc: ${fields.cc.map(address).join(", ")}`] : []),
+        ...(fields.replyTo !== undefined ? [`Reply-To: ${address(fields.replyTo)}`] : []),
+        `Subject: ${word(fields.subject)}`,
+        ...(given("date") ? [] : [`Date: ${rfc5322Date(now)}`]),
+        ...(given("message-id") ? [] : [`Message-ID: <${randomUUID()}@postmock>`]),
+        "MIME-Version: 1.0",
+        ...fields.headers.map((h) => `${h.name}: ${word(h.value)}`),
+    ];
+    const body = attachments.length > 0 ? multipart("mixed", [content, ...attachments]) : content;
+    return `${headers.join("\r\n")}\r\n${body}`;
+}

package/dist/src/pipeline/addresses.d.ts

@@ -0,0 +1,6 @@
+import type { Address } from "../state/types.ts";
+/**
+ * Splits a Postmark address list: commas outside double quotes separate entries; each entry is
+ * `addr` or `[name] <addr>` (docs/03 §1.8, INFERRED). Returns undefined for a malformed entry.
+ */
+export declare function parseAddressList(raw: string): Address[] | undefined;

package/dist/src/pipeline/addresses.js

@@ -0,0 +1,38 @@
+/**
+ * Splits a Postmark address list: commas outside double quotes separate entries; each entry is
+ * `addr` or `[name] <addr>` (docs/03 §1.8, INFERRED). Returns undefined for a malformed entry.
+ */
+export function parseAddressList(raw) {
+    const entries = [];
+    let current = "";
+    let quoted = false;
+    for (const char of raw) {
+        if (char === '"')
+            quoted = !quoted;
+        if (char === "," && !quoted) {
+            entries.push(current);
+            current = "";
+        }
+        else {
+            current += char;
+        }
+    }
+    entries.push(current);
+    const addresses = [];
+    for (const entry of entries.map((e) => e.trim())) {
+        if (entry === "")
+            continue;
+        const named = /^(.*?)\s*<([^<>\s]+@[^<>\s]+)>$/.exec(entry);
+        if (named?.[2] !== undefined) {
+            const name = (named[1] ?? "").replace(/^"(.*)"$/, "$1").replace(/\\"/g, '"');
+            addresses.push({ Email: named[2], Name: name === "" ? null : name });
+        }
+        else if (/^[^<>\s"]+@[^<>\s"]+$/.test(entry)) {
+            addresses.push({ Email: entry, Name: null });
+        }
+        else {
+            return undefined;
+        }
+    }
+    return addresses;
+}

package/dist/src/pipeline/inactive.d.ts

@@ -0,0 +1,8 @@
+import { type ErrorBody } from "../errors.ts";
+/** 406 for a single send: the SDK fixture text (docs/03 §3.2, docs/01 §4.1). */
+export declare const inactiveRecipientsError: (addresses: readonly string[]) => ErrorBody;
+/**
+ * A batch item carries its own 406 wording, with a trailing space (refs/api_email-api.md:301-313).
+ * Other errors are the same as on a single send.
+ */
+export declare function batchItemError(error: ErrorBody): ErrorBody;

package/dist/src/pipeline/inactive.js

@@ -0,0 +1,20 @@
+import { errorBody } from "../errors.js";
+/** 406 for a single send: the SDK fixture text (docs/03 §3.2, docs/01 §4.1). */
+export const inactiveRecipientsError = (addresses) => errorBody(406, { params: { addresses: addresses.join(", ") } });
+// The gem regex (docs/01 §4.1): the strictest of the three SDK regexes.
+const ADDRESSES = /Found inactive addresses: (.+?)\. Inactive/;
+/**
+ * A batch item carries its own 406 wording, with a trailing space (refs/api_email-api.md:301-313).
+ * Other errors are the same as on a single send.
+ */
+export function batchItemError(error) {
+    if (error.ErrorCode !== 406)
+        return error;
+    const addresses = ADDRESSES.exec(error.Message)?.[1];
+    if (addresses === undefined)
+        throw new Error(`406 without an address list: ${error.Message}`);
+    return {
+        ErrorCode: 406,
+        Message: `You tried to send to a recipient that has been marked as inactive. Found inactive addresses: ${addresses}. Inactive recipients are ones that have generated a hard bounce, a spam complaint, or a manual suppression. `,
+    };
+}

package/dist/src/pipeline/submit.d.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { type ErrorBody } from "../errors.ts";
+import type { ServerAuth } from "../http/routes.ts";
+import type { Runtime } from "../runtime.ts";
+import { type TestTokenContext } from "../state/servers.ts";
+import type { Address, OutboundMessage } from "../state/types.ts";
+/**
+ * One message exactly as its channel received it: `/email` and batch JSON values (T1), templates
+ * and bulk after render (T3), SMTP header text and MIME parts (T6). `validateOutbound` owns every
+ * Postmark data check (types, address syntax, required fields, limits, enums), so each ErrorCode has one
+ * source. `undefined` means the sender left the field out.
+ */
+export type OutboundDraft = Record<keyof ReturnType<typeof draftSchema>["shape"], unknown>;
+/** Field shape checks, in draft field order. REST sends JSON types; SMTP sends header text (docs/07 §1.3). */
+declare const draftSchema: (channel: "rest" | "smtp") => z.ZodObject<{
+    From: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    To: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    Cc: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    Bcc: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    ReplyTo: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    Subject: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    HtmlBody: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    TextBody: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    Tag: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    MessageStream: z.ZodPreprocess<z.ZodOptional<z.ZodString>, unknown>;
+    Headers: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        Name: z.ZodString;
+        Value: z.ZodString;
+    }, z.core.$strip>>>, unknown>;
+    Attachments: z.ZodPreprocess<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        Name: z.ZodString;
+        Content: z.ZodPipe<z.ZodString, z.ZodTransform<Buffer<ArrayBuffer>, string>>;
+        ContentType: z.ZodString;
+        ContentID: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>, unknown>;
+    Metadata: z.ZodPreprocess<z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodString>, unknown>>, unknown>;
+    TrackOpens: z.ZodPreprocess<z.ZodOptional<z.ZodBoolean>, unknown> | z.ZodPreprocess<z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<boolean, string>>>, unknown>;
+    TrackLinks: z.ZodPreprocess<z.ZodOptional<z.ZodEnum<{
+        HtmlAndText: "HtmlAndText";
+        HtmlOnly: "HtmlOnly";
+        None: "None";
+        TextOnly: "TextOnly";
+    }>>, unknown>;
+}, z.core.$strip>;
+type Draft = z.output<ReturnType<typeof draftSchema>>;
+/**
+ * The draft of one JSON message object. Keys match without case at every level, `ContentId` too
+ * (docs/08 R8); unknown keys are ignored (R12). Every JSON channel builds its draft here.
+ */
+export declare function draftFromJson(body: Record<string, unknown>): OutboundDraft;
+/**
+ * A REST submission gets its MIME source from the pipeline, written from the draft. An SMTP
+ * submission carries `rawSource`: the delivered copy the dump endpoint serves.
+ */
+export type Submission = {
+    /** A test context is `POSTMARK_API_TEST`: validate, never store or deliver (docs/02 §3.3). */
+    auth: ServerAuth | TestTokenContext;
+    draft: OutboundDraft;
+    /** Request JSON (REST) or raw MIME (SMTP), kept for `GET /control/messages`. */
+    request: unknown;
+    bulkRequestId: string | null;
+    templateId: number | null;
+} & ({
+    channel: "rest";
+} | {
+    channel: "smtp";
+    rawSource: string;
+});
+export type SubmitResult = {
+    outcome: "accepted";
+    message: OutboundMessage;
+}
+/** Test token: valid, not stored. */
+ | {
+    outcome: "validated";
+    messageId: string;
+    submittedAt: Date;
+} | {
+    outcome: "rejected";
+    error: ErrorBody;
+}
+/**
+ * Some recipients suppressed: the rest were accepted, the caller answers 406. INFERRED from an
+ * unverified integrator report (docs/04 §3.3, Q6).
+ */
+ | {
+    outcome: "partiallySuppressed";
+    message: OutboundMessage;
+    error: ErrorBody;
+};
+/** A draft that passed every data check, ready for `acceptOutbound`. */
+export interface ValidOutbound {
+    submission: Submission;
+    draft: Draft & {
+        From: string;
+        To: string;
+    };
+    streamId: string;
+    from: Address;
+    lists: Record<"To" | "Cc" | "Bcc" | "ReplyTo", Address[]>;
+    recipients: Address[];
+}
+export type Validation = {
+    outcome: "valid";
+    outbound: ValidOutbound;
+}
+/**
+ * `field` keys the bulk `Errors` map (refs/api_bulk-email.md:213-231). Which field Postmark
+ * names is documented for addresses only; the others are INFERRED.
+ */
+ | {
+    outcome: "rejected";
+    field: string;
+    error: ErrorBody;
+};
+/**
+ * The checks of a send, with no state change: the data checks (field types, size, stream,
+ * addresses, recipients, content, limits, attachments) and the sender check. Account approval and
+ * suppressions belong to `acceptOutbound`. Throws `Unsupported` for uncaptured cases.
+ */
+export declare function validateOutbound(runtime: Runtime, submission: Submission): Validation;
+/**
+ * Which error Postmark answers for a message that fails a data check and the sender check is not
+ * captured (docs/03 §3.4). A caller that answers a data error calls this first. The test token
+ * belongs to no account and has no sender check (sdk/postmark-gem/spec/integration/api_client_messages_spec.rb:5-10,
+ * :45-48; sdk/postmark-java/src/test/java/integration/MessageTest.java:27-36).
+ */
+export declare function refuseSenderAfterDataError(runtime: Runtime, auth: Submission["auth"], rawFrom: unknown): void;
+/**
+ * Stores every accepted message, then emits `sent` for each, in order. A `sent` listener that
+ * changes state (archives a stream, adds a suppression) cannot affect a later message of the
+ * same request.
+ */
+export declare function acceptOutbounds(runtime: Runtime, outbounds: readonly ValidOutbound[]): Promise<SubmitResult[]>;
+export declare function acceptOutbound(runtime: Runtime, outbound: ValidOutbound): Promise<SubmitResult>;
+/** `validateOutbound`, then `acceptOutbound` for a valid draft. */
+export declare function submitOutbound(runtime: Runtime, submission: Submission): Promise<SubmitResult>;
+export {};