Send email from DaloyJS with Postmark

POSTMARK_SERVER_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
POSTMARK_STREAM=outbound
POSTMARK_WEBHOOK_USER=postmark
POSTMARK_WEBHOOK_PASSWORD=a-long-random-string-from-your-secret-store
EMAIL_FROM="Acme <no-reply@mail.acme.example.com>"

import { ServerClient } from "postmark";
import type { EmailSender } from "../plugins/email.ts";
import { config } from "../config.ts";

export const postmark = new ServerClient(config.POSTMARK_SERVER_TOKEN, {
  timeout: 10, // seconds; the SDK default is 60
});

export const sender: EmailSender = {
  async send(msg) {
    const res = await postmark.sendEmail({
      From: config.EMAIL_FROM,
      To: msg.to,
      ReplyTo: msg.replyTo,
      Subject: msg.subject,
      TextBody: msg.text,
      HtmlBody: msg.html,
      Headers: msg.headers
        ? Object.entries(msg.headers).map(([Name, Value]) => ({ Name, Value }))
        : undefined,
      MessageStream: config.POSTMARK_STREAM,
    });
    // The SDK throws typed errors on failure; keep a defensive check anyway.
    if (res.ErrorCode !== 0) throw new Error(`Postmark error ${res.ErrorCode}`);
    return { id: res.MessageID };
  },
};

import { z } from "zod";
import { App, NotFoundError, UnauthorizedError, jobIdempotencyKey } from "@daloyjs/core";
import { escapeHtml } from "../plugins/email.ts";
import { sendGuards } from "../email/guards.ts";

export function receiptRoutes(app: App) {
  app.post(
    "/orders/:orderId/receipt",
    {
      operationId: "emailReceipt",
      hooks: sendGuards, // auth + per-IP + per-user limits, see the overview
      request: { params: z.object({ orderId: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/) }) },
      responses: {
        202: { description: "Queued", body: z.object({ jobId: z.string() }) },
      },
    },
    async ({ params, state }) => {
      const sub = state.user?.sub;
      if (!sub) throw new UnauthorizedError();
      const order = await findOrderForUser(params.orderId, sub);
      if (!order) throw new NotFoundError(); // same answer for "missing" and "not yours"
      const total = (order.totalCents / 100).toFixed(2);
      const { job } = await app.jobs!.enqueue({
        name: "email.send",
        payload: {
          to: order.customerEmail,
          subject: `Receipt for order ${order.id}`,
          text: `Thanks ${order.customerName}. Total: ${total} ${order.currency}`,
          html: `<p>Thanks ${escapeHtml(order.customerName)}.</p><p>Total: <strong>${total} ${escapeHtml(order.currency)}</strong></p>`,
        },
        idempotencyKey: jobIdempotencyKey({ name: "email.send", key: `receipt-${order.id}` }),
      });
      return { status: 202, body: { jobId: job.id } };
    },
  );
}

declare function findOrderForUser(
  orderId: string,
  userId: string,
): Promise<{ id: string; customerEmail: string; customerName: string; totalCents: number; currency: string } | null>;

await postmark.sendEmailWithTemplate({
  From: config.EMAIL_FROM,
  To: order.customerEmail, // looked up server-side
  TemplateAlias: "order-receipt",
  TemplateModel: { name: order.customerName, orderId: order.id, total },
  MessageStream: "outbound",
});

import { Errors } from "postmark";
import { JobFatalError } from "@daloyjs/core";

// Inside the overview's "email.send" job handler:
try {
  await sender.send({ ...msg, signal });
} catch (err) {
  if (err instanceof Errors.InactiveRecipientsError) {
    for (const email of err.recipients) await markUndeliverable(email.toLowerCase(), "inactive");
    throw new JobFatalError("Postmark: inactive recipient"); // dead-letter, no retries
  }
  throw err; // transient: the worker retries with backoff
}

import { z } from "zod";
import { App, basicAuth, jobIdempotencyKey, readBodyLimited, safeJsonParse, timingSafeEqual } from "@daloyjs/core";
import { config } from "../config.ts";

interface PostmarkEvent {
  RecordType: string; // "Bounce", "SpamComplaint", "Delivery", ...
  Type?: string; // on bounces: "HardBounce", "SoftBounce", ...
  ID?: number;
  MessageID?: string;
  Email?: string;
}

export function postmarkWebhookRoutes(app: App) {
  app.post(
    "/webhooks/postmark",
    {
      operationId: "postmarkEvents",
      hooks: basicAuth({
        realm: "postmark-webhooks",
        verify: (user, pass) => {
          // Evaluate both so timing does not reveal which half was wrong.
          const userOk = timingSafeEqual(user, config.POSTMARK_WEBHOOK_USER);
          const passOk = timingSafeEqual(pass, config.POSTMARK_WEBHOOK_PASSWORD);
          return userOk && passOk;
        },
      }),
      responses: {
        200: { description: "Accepted", body: z.object({ ok: z.literal(true) }) },
      },
    },
    async ({ request }) => {
      const raw = new TextDecoder().decode(await readBodyLimited(request, 256 * 1024));
      const event = safeJsonParse(raw) as PostmarkEvent | undefined;
      const hard =
        (event?.RecordType === "Bounce" && event.Type === "HardBounce") ||
        event?.RecordType === "SpamComplaint";
      if (event && hard && event.Email && event.ID !== undefined) {
        await app.jobs!.enqueue({
          name: "email.suppress",
          payload: { email: event.Email, reason: event.RecordType },
          // Postmark retries reuse the same record ID.
          idempotencyKey: jobIdempotencyKey({ name: "email.suppress", key: `pm-${event.RecordType}-${event.ID}` }),
        });
      }
      return { status: 200, body: { ok: true as const } }; // ack fast
    },
  );
}

import { env } from "cloudflare:workers";
import type { EmailSender } from "../plugins/email.ts";
import { providerFetch } from "./fetch.ts"; // allowHosts: ["api.postmarkapp.com"]

export const sender: EmailSender = {
  async send(msg) {
    const res = await providerFetch("https://api.postmarkapp.com/email", {
      method: "POST",
      headers: {
        accept: "application/json",
        "content-type": "application/json",
        "x-postmark-server-token": env.POSTMARK_SERVER_TOKEN,
      },
      signal: msg.signal,
      body: JSON.stringify({
        From: env.EMAIL_FROM,
        To: msg.to,
        ReplyTo: msg.replyTo,
        Subject: msg.subject,
        TextBody: msg.text,
        HtmlBody: msg.html,
        MessageStream: "outbound",
      }),
    });
    const out = (await res.json()) as { ErrorCode: number; MessageID?: string };
    if (!res.ok || out.ErrorCode !== 0) throw new Error(`Postmark error ${out.ErrorCode}`);
    return { id: out.MessageID ?? "" };
  },
};