Postmark’s single-send endpoint accepts one JSON message, while its batch endpoint allows up to 500 messages per request—but individual messages in a batch can still fail. That distinction is one reason AI-generated integration code can look complete while missing operational behavior.

This postmark api guide covers the first request, credentials, batch handling, and the supporting tools you’ll need to make an integration production-ready. To send through Postmark, create a server, confirm a sender, copy its Server Token, then POST JSON to https://api.postmarkapp.com/email with the X-Postmark-Server-Token header. For multiple messages, use /email/batch and inspect each result. Add templates, Message Streams, and webhooks as your application needs them.

What Postmark’s API does—and where AI Skills fit

Postmark’s API sends email for a particular Postmark server and exposes tools for managing parts of the surrounding email setup. Its Email API reference documents single sends and batch sends. The API can also work with templates and Message Streams. Postmark is especially oriented toward transactional email; broadcast streams and campaign-oriented features are separate considerations from sending an application-triggered receipt or password reset.

That distinction matters when you’re choosing an integration. Sending a welcome message after signup is transactional; managing a broader marketing program may call for a platform with campaign and automation capabilities as well as sending.

AI coding agents add another layer: an agent needs current instructions, not just a token and endpoint. Postmark’s February 2026 announcement introduced open-source Skills covering five areas: sending, inbound email, templates, webhooks, and email best practices. A Skill gives an agent structured implementation guidance; it does not authenticate the application or replace the API request itself.

Make your first request with the Postmark API

Set up the server and credential

Create a Postmark server and confirm the sender address or domain you intend to use. Then open that server’s API Tokens tab and copy its Server Token. Postmark’s API overview specifies the X-Postmark-Server-Token header for server-level requests; an account token is a different credential for account-level operations.

Keep the Server Token in a server-side environment variable or secret store. Do not put it in browser code, a mobile app bundle, or a repository. A token exposed to users can let someone make requests with your server’s privileges.

Send one message

Here is a compact curl example. Replace the sender with a confirmed address, the recipient with a real test inbox, and the environment variable with your server’s token:

curl "https://api.postmarkapp.com/email" \\
  -X POST \\
  -H "Accept: application/json" \\
  -H "Content-Type: application/json" \\
  -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \\
  -d '{"From":"Billing <billing@example.com>","To":"person@example.net","Subject":"Receipt ready","TextBody":"Your receipt is available.","MessageStream":"outbound"}'

From, To, and Subject identify the message, while TextBody provides its plain-text content. You can use HtmlBody for HTML content. MessageStream selects the stream; when omitted, Postmark documents the default as the outbound transactional stream. A successful response includes message-result data such as a message ID and submission time, which you can log for support and debugging.

Batch messages carefully

For multiple distinct messages, POST a JSON array to /email/batch. Postmark documents a maximum of 500 messages and a 50 MB total payload, including attachments. Batch requests reduce the number of HTTP calls for queued work, but they don’t turn the messages into one all-or-nothing operation.

Check the result for every item: Postmark can return a 200-level HTTP status even when validation fails for individual messages. Match results to inputs by their order, then record each item’s success or error code. See the batch email guide for the current request shape and constraints.

Use streams, templates, domains, and webhooks

Message Streams help separate kinds of sending. Choose the stream that matches the message rather than assuming every message should use the transactional default. Postmark’s API also supports template-based sending; templates keep message content outside application code and are useful when several messages share a layout or need non-code edits. Its Skills article recommends template aliases over IDs for workflows where templates may be recreated or moved between servers.

For setup and troubleshooting, the Domains API helps manage domain-related configuration, while Postmark’s API Explorer lets you inspect and submit API requests interactively. Treat Explorer actions as real requests against the account, not as a dry-run by default; take care when testing with production credentials or recipients.

Webhooks let your application react to events such as delivery, bounce, open, click, spam complaint, and subscription change. Configure only the events your system needs, then make the handler safe to call more than once: persist the event, update the relevant record, and avoid repeating a side effect on duplicate processing. Postmark’s Webhooks API reference describes verification: enabled event checks must receive a successful response for the webhook to be verified.

Errors, limits, and production checks

Before shipping, test more than the happy path. Postmark’s API overview describes 401 for missing or incorrect authentication, 413 for requests that exceed payload limits, and 429 when request rates exceed acceptable use. The overview does not give a single universal numeric rate threshold, so don’t build a fixed throughput assumption from the status code alone.

Use this checklist before enabling real traffic:

  • Confirm the sender and stream in a test environment, then check the recipient and message content.
  • Handle non-2xx responses, including authentication, payload-size, and rate-limit errors; don’t retry a request that needs a configuration fix as if it were transient.
  • For batch sends, inspect each message result, not just the HTTP status.
  • For webhooks, verify the endpoint and design event processing to tolerate repeated delivery.
  • Keep credentials out of client code and logs, and retain message IDs and event data useful for support.

Postmark’s open-source Skills can help an AI agent remember implementation details such as batch handling, stream selection, error handling, and webhook setup. The project’s article gives npx skills add ActiveCampaign/postmark-skills as the installation command. Treat generated code as a draft: review the credentials, request fields, recipient behavior, and failure paths before deploying it.

When Postmark fits—and when to consider another stack

Postmark is a good fit when the central requirement is application email, especially transactional messages, and the team wants Postmark’s servers, streams, templates, and event tooling around that work. Its API documentation and Skills can give developers and coding agents concrete implementation context, but an agent still needs review and properly scoped credentials.

If one system also needs campaigns, automated workflows, large contact storage, or tools for an AI agent to operate the email platform, compare that broader scope explicitly. Volanea combines Amazon SES-backed transactional email, campaigns, and automations in one API, with unlimited contact storage. Its MCP server is available on every plan and provides 23 tools. Our AI-agent email platform guide explains that integration path; for agent-driven sending, see our notes on email AI agent security. These capabilities address a broader workflow and aren’t interchangeable with Postmark’s focused sending API.

FAQ

Where do I find a Postmark Server Token?

Open the Postmark server you’ll use and find its API Tokens tab. Copy the Server Token for requests that need server-level access, then store it on your backend as a secret. Use the header X-Postmark-Server-Token when making the API request, and don’t expose the token in client-side code.

What happens if some messages in a batch fail?

A successful HTTP status does not mean every message in the batch succeeded. Inspect each item in the response and use its error code and message to decide what to fix or retry. Record results per recipient so a partial failure doesn’t cause your application to resend messages that were already accepted.

Are Postmark Skills the same as Postmark MCP?

No. Skills provide an AI coding agent with structured guidance for writing code that uses Postmark. MCP gives an AI tool a way to interact with an account through available tools. Postmark describes them as complementary: one helps the agent implement an integration, while the other supports direct account actions.

When should I choose a broader email platform?

Consider a broader platform when transactional sending is only one part of the system—for example, when the same team also needs campaigns, automated workflows, or an AI agent to operate email tooling. Compare those requirements separately from API quality, and check whether the platform’s contact model and agent interfaces suit your application.

If your stack needs transactional email, campaigns, automations, and MCP access in one place, start free with 1,000 emails a month.