Next.js boilerplate with Postmark

One send path

sendEmail() from @/lib/email is the only way this app sends mail.

• Nothing else imports postmark, builds a ServerClient, or reads POSTMARK_SERVER_TOKEN.
• The client lives in src/lib/email/postmark.ts and is built on first use. Never at module scope: next build imports every route with no secrets set.
• The Resend and Mailgun batteries export the same sendEmail, SendEmailOptions, SendEmailResult, EmailAttachment and EmailSuppressedError. Keep it that way. Add options, never rename or narrow them.
• Postmark-only options: stream, tag, tracking. Shared callers (auth, billing) must not set them.

import { sendEmail } from "@/lib/email";
import ReceiptEmail from "@/lib/email/templates/receipt";

await sendEmail({
  to: user.email,
  subject: `Receipt ${payment.reference}`,
  react: ReceiptEmail({ reference: payment.reference /* ... */ }),
  idempotencyKey: `receipt:${payment.id}`,
  tag: "receipt",
});

Message streams

Postmark splits mail into streams. They use separate IP pools and separate suppression lists.

Stream	Env	Default id	For
Transactional	POSTMARK_MESSAGE_STREAM	outbound	Anything the user just triggered: sign-in, reset, receipt, invite
Broadcast	POSTMARK_BROADCAST_STREAM	broadcast	Newsletters, announcements, digests, promos

• sendEmail defaults to transactional. Broadcast is stream: "broadcast", per send.
• Never send marketing through the transactional stream. One promo blast that draws complaints hurts every magic link after it. Postmark's sending policy requires the split.
• A "transactional" email with a promo paragraph is marketing. Keep receipts and welcome mails free of upsells.
• On broadcast, Postmark adds the unsubscribe link and List-Unsubscribe headers. Do not add your own.
• Never call messageStream() with a hardcoded id. Streams are configured by env.

Inactive recipients

Postmark deactivates an address after a hard bounce or a spam complaint. A later send to it fails with error 406.

• sendEmail turns that 406 into EmailSuppressedError. Same error as a local hit.
• Do not catch EmailSuppressedError and retry, resend through another path, or "fix" it by reactivating. The address is dead or the person said stop.
• Do show it to support: "we can't email this address, ask the user for a new one."
• The local list (src/lib/email/store.ts) mirrors the transactional stream. The webhook fills it. isSuppressed fails open on a database error on purpose. Postmark still enforces.
• unsuppress() is for an explicit request from the mailbox owner. Postmark will not reactivate a spam complaint through the API. Never bulk-reactivate.
• suppress(address, "manual") writes to Postmark too. The webhook passes { mirrored: true } so it never writes back.

The webhook

src/app/api/webhooks/postmark/route.ts.

• Postmark does not sign webhooks. The check is basic auth: POSTMARK_WEBHOOK_USERNAME / POSTMARK_WEBHOOK_PASSWORD, compared in constant time in webhook-auth.ts.
• Never weaken it: no "skip auth in dev", no query-string secret, no IP check alone.
• Missing credentials means 503, not an open door.
• Every write is an upsert. Postmark retries any non-2xx, so a redelivery must change nothing.
• Hard bounce (Inactive: true) and spam complaint suppress from any stream. SubscriptionChange acts on the transactional stream only.

Idempotency

Postmark has no idempotency key. idempotencyKey becomes a deterministic Message-ID header plus idempotency_key metadata.

• Scope it to the event: receipt:${paymentId}, welcome:${userId}. Never a timestamp or a random value.
• No key on a magic link. A second request must send a second link.

Metadata, tags and tracking

• tags becomes Postmark Metadata. At most 10 fields (9 with an idempotency key), names up to 20 characters, values up to 80. tags.ts enforces it.
• tag is the single Postmark Tag for stats. A category like receipt. Never an id or an address.
• tracking is off unless a person decided otherwise. Never on a magic link, reset or receipt. Tracked links get rewritten, and a rewritten sign-in link is a phishing signal.

Secrets and content

• No API keys, env values, passwords or session tokens in any email body.
• A magic link is the one credential a message may carry. Pass the URL as a prop. Never log it.
• Templates live in src/lib/email/templates as React Email components. sendEmail renders HTML and text. Never build HTML with string concatenation.
• Every template takes a locale. Pass the recipient's.

The Postmark MCP server

.mcp.json ships the official Postmark MCP server. Use it to diagnose: diagnoseDelivery, searchOutboundMessages, searchBounces, getMessageDetails.

• Never use its send tools to mail a real person. Test sends go through bun run email:send-test.
• Never create, edit or delete Postmark templates with it. Templates live in this repo.