DEV Community

TateFletcher6754
TateFletcher6754

Posted on

Create Node.js Transactional Email Templates for Seller Orders with Preview Evidence

#node #email #observability

Short answer: keep the seller's new-order email template under the team's change control, preview the exact version and sample order that will be sent, and record that version alongside each delivery attempt. In Node.js, rendering and dispatch should be separate steps. A successful send request proves neither inbox placement nor even final delivery.

The old mental model is one mutable template plus a send() call. The useful one is a chain: order event, immutable template revision, rendered subject and bodies, queued attempt, transport result, delivery evidence. Each link has an owner. That makes a changed pickup instruction visible before it reaches a seller, and makes a missing notification diagnosable afterward.

Those are separate claims.

Who owns the seller-facing words?

For a marketplace support team, the new-order email may contain an order reference, item summary, and a link to the seller's order view. The service that understands those fields should own the input contract. The team responsible for seller communications should approve wording and the rendered preview. The delivery adapter should accept the finished message and report what happened; it should not silently choose a different revision.

There is a real trade-off here. Storing templates in the application repository makes reviews and rollback straightforward, but a copy change goes through deployment. An external template editor can give a communications team a shorter editing loop, but a mutable remote template identifier does not establish which copy a queued order will use. Either arrangement can work if publication yields a revision identifier and each queued job pins it. Start with a repository-owned revision when the same team owns both code and copy; change that boundary only when the approval workflow calls for it.

Keep the preview check close to the sender's actual data. A sample with a one-character seller name will miss a long-name layout defect. A sample with every optional field populated will miss empty values. For example, imagine approving a preview with an item summary and a short seller name, then dispatching a new order whose optional item label is missing and whose seller name is much longer. A screenshot of the approved sample says nothing about that second rendering. Test at least one ordinary order and one order with an absent optional field, then compare the rendered subject, plain-text body, and HTML body against the approved revision. Test long values too, and check the final link destination rather than trusting its visible label. This is a content check, not a deliverability measurement; mail authentication and transport outcomes need their own evidence.

How do you create and preview transactional email templates in Node.js?

Here is a small TypeScript boundary. The transport is deliberately generic; the interesting contract is that preview and send call the same renderer. Publishing an update means adding a new revision to the registry, reviewing its preview, and switching the revision chosen for new jobs. Existing jobs retain their pinned revision.

type OrderNotice = {
  orderId: string;
  sellerEmail: string;
  sellerName: string;
  itemCount: number;
  orderUrl: string;
};

type Message = { to: string; subject: string; text: string; html: string };
type Transport = { send(message: Message): Promise<{ attemptId: string }> };

const revisions = {
  "seller-order-v1": (order: OrderNotice): Message => {
    const name = escapeHtml(order.sellerName);
    const url = escapeHtml(order.orderUrl);
    return {
      to: order.sellerEmail,
      subject: `New order ${order.orderId}`,
      text: `Hello ${order.sellerName}, order ${order.orderId} has ${order.itemCount} item(s). View it: ${order.orderUrl}`,
      html: `<p>Hello ${name},</p><p>Order ${order.orderId} has ${order.itemCount} item(s). <a href="${url}">View order</a>.</p>`,
    };
  },
} satisfies Record<string, (order: OrderNotice) => Message>;

function escapeHtml(value: string): string {
  return value.replace(/[&<>"']/g, char => ({
    "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
  })[char]!);
}

type Revision = keyof typeof revisions;
type Job = { order: OrderNotice; revision: Revision };

function preview(job: Job): Message {
  return revisions[job.revision](job.order);
}

async function sendJob(job: Job, transport: Transport) {
  const rendered = preview(job);
  const result = await transport.send(rendered);
  return { orderId: job.order.orderId, revision: job.revision, attemptId: result.attemptId };
}
Enter fullscreen mode Exit fullscreen mode

The example assumes the order ID is generated by the application, the order URL is validated as an approved HTTPS destination before entering the job, and the item count is a nonnegative integer. Validate those at the input boundary; HTML escaping alone does not validate a link destination or prevent control characters in a mail header. In production, render from an immutable order snapshot if the notification must describe the order as it stood when the event was recorded.

Before release, run preview() against fixture jobs for both the current and candidate revision, inspect the difference, and exercise sendJob() with a test transport that captures the message without mailing a real seller. A review should cover text and HTML independently. The HTML can look fine while the text version carries an old link.

That's easy to miss.

What if the same order event arrives twice?

Pinning a revision does not make sending exactly once. A worker can submit a message and lose its acknowledgment; retrying then risks a duplicate. Give the notification a stable application key such as (orderId, seller-order-created, sellerId), persist the queued job and its revision, and record attempts separately. If the transport supports an idempotency key, pass the stable key through. If it does not, a local uniqueness constraint can stop duplicate jobs, but it cannot resolve an unknown result after a remote submission. Treat that state explicitly instead of claiming guaranteed single delivery.

Observe the chain without logging seller names, addresses, message bodies, or order links. Useful structured fields are event type, order correlation ID, revision, attempt ID, submission outcome, and timestamps. Count queued jobs, submission failures, and delayed attempts by revision; alert when the age of the oldest unsent job exceeds the team's notification target. Keep transport acceptance and any subsequent delivery or bounce event as different states. No callback is not proof of delivery.

Neither is a green worker metric.

DKIM signs selected email headers and the body so a receiver can verify the signing domain's responsibility for the message. It is one authentication signal, not a promise of inbox placement. Check the configured sending domain and authentication before rollout, then monitor rejection and bounce evidence as revisions go live. If you also send account-recovery messages, do not reuse this order template or its data contract: recovery tokens need their own security controls.

Does every wording change require a deployment?

No. It requires a publication boundary. An editor-backed store can publish immutable revisions and expose a preview against representative order fixtures; a repository can do the same through review and deployment. Choose based on who must approve the words and how quickly corrections must ship. The invariant is that the previewed revision equals the revision the worker renders, even when a job waits in a queue during an update.

The extra storage and review steps have a cost. They buy a narrower debugging question: which revision produced this attempt, and what did the transport report? For seller support, that answer is more useful than a dashboard showing only that the worker ran.

References

Further reading

Top comments (0)