Postmark Transactional Email
Send transactional email through a Postmark server (plain or from a template), search sent messages and read their delivery details, and check bounces and delivery statistics. Based on the Postmark API specification.
Connect this API to an AI agent Browse all specs
What you can do with Postmark Transactional Email via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /messages/outbound |
searchOutboundMessages | Search sent emails by recipient, sender, tag, status or date |
| GET | /messages/outbound/{messageid}/details |
getOutboundMessageDetails | Get a sent email with its delivery events |
| GET | /bounces |
getBounces | List bounced emails |
| GET | /bounces/{bounceid} |
getBounce | Get details of one bounce |
| GET | /deliverystats |
getDeliveryStats | Get bounce totals by type and inactive mail count |
| GET | /stats/outbound |
getOutboundOverview | Get sent, bounce, spam, open and click totals for a period |
| GET | /templates |
listTemplates | List email templates on the server |
| GET | /templates/{templateIdOrAlias} |
getTemplate | Get a template by id or alias |
| POST | /email |
sendEmail | Send a single email |
| POST | /email/withTemplate |
sendEmailWithTemplate | Send an email from a template |
Authentication
ServerToken
API key — sent as the X-Postmark-Server-Token header
Postmark Server API token sent in the X-Postmark-Server-Token header.
How to get a credential
- Sign in to Postmark (account.postmarkapp.com).
- Open Servers and select the server that sends your email.
- Open the API Tokens tab and copy a Server API token (not the Account API token).
- Make sure your sender signature or domain is confirmed under Sender Signatures.
Permissions used
| Token | Operations |
|---|---|
| Server API token (read) | searchOutboundMessages, getOutboundMessageDetails, getBounces, getBounce, getDeliveryStats, getOutboundOverview, listTemplates, getTemplate |
| Server API token (send) | sendEmail, sendEmailWithTemplate |
A server token is scoped to one server; use one credential per server.
Common errors
- 401 Unauthorized: the token is missing or wrong, or you used the Account token. Copy a Server API token.
- 422 Unprocessable Entity: Postmark's validation error (e.g. ErrorCode 300 invalid email, 400 sender signature not confirmed, 406 inactive recipient). Read
ErrorCodeandMessagein the response. - 400 / 413: malformed JSON or message too large.
- 429 Too Many Requests: rate limit hit; wait and retry.
Store the token as a VX Agents credential (API key, header X-Postmark-Server-Token); never paste it into chat.
Usage guide
Setup
- Add the Server API token of the Postmark server you send from as the credential (header
X-Postmark-Server-Token). One credential = one server. - Pin your confirmed sender (
From, e.g.Acme Support <[email protected]>) so every send uses a verified sender signature.
Send an email
- For a template, call
listTemplates(CountandOffsetare required, e.g. 50 and 0), thengetTemplateto see its subject/body and the variables it expects. - Show the user the recipient, subject and content (or template + data) and get confirmation.
- Call
sendEmailwithFrom,To,SubjectandHtmlBodyand/orTextBody, orsendEmailWithTemplatewithFrom,To,TemplateIdorTemplateAlias(not both) andTemplateModel(the variables). - Keep the returned
MessageID.ErrorCode0 means accepted.
Check delivery
searchOutboundMessagesbyrecipient,fromemail,tag,statusor date range (countmax 500,offsetrequired).getOutboundMessageDetailswith theMessageIDto see delivery, bounce, open and click events.getBounces(filter bytype,emailFilter,inactive, dates) andgetBouncefor the reason;getDeliveryStatsfor totals.getOutboundOverviewfor sent, bounce, spam-complaint, open and click totals overfromdate/todate.
Good to know
- Sending reaches real customers: always confirm
sendEmailandsendEmailWithTemplatebefore calling them. - Dates are
YYYY-MM-DD. Message ids are UUIDs; bounce ids are integers. Toaccepts a comma-separated list (max 50 recipients). Total message size max 10 MB.- Postmark returns 422 with an
ErrorCodefor validation problems: 300 invalid email, 400 sender signature not confirmed, 406 recipient is inactive (hard bounce or spam complaint). Do not resend to inactive recipients. - Use
Tagon sends to group messages for later search and stats.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Postmark Transactional Email” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.