How should a product team implement the Postmark API safely?

Define the application boundary before Postmark

Start from an authorized business event such as a receipt, verification, requested alert, or security notice. Persist a durable outbound job with a stable event key, tenant, message class, template revision, approved sender and recipients, consent or necessity basis, current suppression decision, and initial state. Browser, mobile, template, and user input must not select a Postmark server token, arbitrary From identity, message stream, webhook, unrestricted recipient, or provider metadata. Put all provider calls behind one server-side adapter. Separate transactional and broadcast or marketing traffic according to the product's consent and reputation model. Postmark's API transports a message; it does not establish tenant authorization, recipient consent, or business idempotency. Claim the internal job once, record every provider attempt, and keep provider identifiers as evidence linked to the application event rather than using them as the only system of record.

Use server tokens with narrow operational scope

Postmark's email API documents the X-Postmark-Server-Token header for server-scoped API access. Store each token in a managed secret service and expose it only to the worker that needs that server and environment. Never place tokens in client code, source control, URLs, logs, analytics, templates, screenshots, tickets, prompts, or test fixtures. Separate production from development and unrelated products so revocation or misuse has a bounded impact. Rehearse rotation by provisioning a replacement through approved administration, updating the worker, sending controlled messages, confirming API and event evidence, then revoking the old token. Treat unexpected authentication errors as a pause condition, not an invitation to retry credentials rapidly. Restrict dashboard administration with strong authentication and roles. A server token authorizes Postmark API operations for its server; the application must still authorize the tenant, sender, recipient, template, and message class.

Verify the exact sender identity

Use a sender signature or verified domain controlled by the organization and confirm the exact From address used by every stream. Inventory the visible From domain, SMTP return path, DKIM d= domain and selector, reply address, and sending message stream on raw received samples. Publish only the DNS records Postmark currently requires for the selected setup, after reviewing existing SPF, DKIM, and DMARC ownership. Preserve previous values and rollback instructions. Provider verification is evidence that its configuration check passed; it does not prove every application path uses that identity, DMARC aligns, recipients consented, or messages reach inboxes. Keep tenant-specific sender authorization in the application and block cross-tenant From values. Test subdomains, replies, bounces, lower environments, and template paths. Do not weaken the organization's SPF or DMARC policy simply to make a dashboard indicator green.

Build one explicit POST email request

Postmark documents POST /email with JSON fields for sender, recipients, subject, text or HTML bodies, ReplyTo, headers, tags or metadata, message stream, attachments, and tracking options. Expose only the fields the product needs. Validate and normalize addresses, bound recipient and attachment counts, reject header injection, escape template values by output context, and generate text and HTML from one approved revision. Do not put secrets or unnecessary personal data in tags, metadata, headers, subjects, or attachment names because they can surface in provider activity and events. Select MessageStream from trusted configuration, never arbitrary request input. Keep the provider payload in one adapter so business code does not depend on every Postmark field. Store a content revision or privacy-safe hash when audit needs justify it rather than logging the full message body.

Interpret the immediate response narrowly

Postmark's single-email endpoint documents response fields including ErrorCode, Message, MessageID, SubmittedAt, and recipient information. Persist the exact HTTP status and structured provider response with the application attempt. A successful response and MessageID show that Postmark accepted the API request under its documented semantics; they do not show that the destination server accepted the message or that it reached an inbox. Classify validation, sender-signature, authentication, malformed payload, quota, and policy errors before retrying. A request timeout is ambiguous because Postmark might have accepted the operation while the client missed the response. Keep that attempt unknown, search provider activity or later events using safe correlation data, and apply a message-class-specific reconciliation rule before resending. Never promise exactly-once delivery or create a new logical event merely because one HTTP request failed.

Design retries around provider and transport evidence

Retry only eligible network failures, rate limits, and provider server errors with exponential backoff, jitter, finite attempts, and queue-age limits. Correct permanent request, sender, recipient, token, template, and policy errors instead of replaying them. Keep the same application event key and record linked attempts. Check suppression and authorization again immediately before each retry because recipient or business state can change while queued. Limit concurrency and rate by server, tenant, message stream, sender domain, and destination cohort so one outage cannot monopolize capacity. Stop on expired events, revoked sender identity, complaint, unsubscribe, permanent recipient failure, or incident pause. Monitor retry age, unknown outcomes, response classes, token failures, and provider latency. If Postmark already performs downstream SMTP retries after acceptance, do not create an aggressive duplicate application loop on top of that transport behavior.

Secure delivery and bounce webhooks

Configure only the Postmark webhook types the application needs and use HTTPS. Apply the current documented webhook security controls, restrict the endpoint to its expected server or stream, enforce request-size and content-type bounds, and never trust message identifiers, recipients, tags, metadata, or diagnostics merely because JSON parses. Persist or enqueue the authenticated or otherwise securely admitted event before returning success. Deduplicate on a stable provider event identifier where available or a conservative composite that cannot merge recipients, event types, or attempts. Preserve occurrence and processing time separately. Expect delay, retry, duplication, and out-of-order delivery. Correlate MessageID and trusted metadata to the internal tenant and job before changing state. Rotate webhook credentials or URLs independently from API tokens, monitor unauthorized requests and lag, and retain raw payloads only as long as operational and policy needs justify.

Model delivery, bounce, and suppression states

Map Postmark delivery and bounce evidence to an internal recipient-level model while retaining the original provider type, MessageID, timestamp, status or bounce classification, and diagnostic. API acceptance, Postmark processing, destination-server acceptance, later nondelivery, mailbox-folder placement, and engagement are different states. A delivered event normally reflects the provider's documented destination-server observation, not a view into the final folder. Temporary failures can justify bounded transport handling; confirmed permanent address failures should create recipient-scoped suppression. Complaints and unsubscribes must update recipient safety before later jobs. Protect manual reactivation with authorization, reason, and audit history. Keep product-owned consent and suppression state so migration does not discard recipient protection. Do not infer human reading from open or click tracking, which is engagement instrumentation and can be affected by privacy technology.

Test sandbox, production, and failure paths

Use Postmark's documented test or sandbox facilities and dedicated controlled recipients, not real customer addresses, for deterministic failures. Test valid and invalid tokens, unauthorized From identities, approved and blocked recipients, text and HTML, Unicode, attachments, metadata minimization, message streams, request timeout before and after acceptance, rate response, webhook authentication, duplicate delivery, out-of-order events, bounce classifications, suppression, and token rotation. Verify raw received headers, DKIM and DMARC alignment, Reply-To, tracking configuration, and MessageID correlation. Confirm lower environments cannot reach production recipients. Run export and migration tests for suppressions and operational evidence. Fail launch on cross-tenant sender or event access, unavailable suppression enforcement, ambiguous webhook admission, secrets in logs, unbounded retries, or an inability to pause the affected server or stream safely.

How SendHQ fits

SendHQ is a workspace-scoped email API for expected product communication. Its public documentation covers verified-domain sending, inbound email, hosted templates, delivery events, suppressions, and a web dashboard.

Frequently asked questions

Sources

• Postmark Email API — Postmark
• Postmark API overview — Postmark
• Postmark Webhooks overview — Postmark
• Postmark Bounce webhook — Postmark
• RFC 5321: Simple Mail Transfer Protocol — RFC Editor