Postmark API
The Postmark API sends, tracks and manages transactional and broadcast email. It is a REST API that accepts and returns JSON over HTTPS.
Official documentation: https://postmarkapp.com/developer
Authentication
Every request must carry an API token in a header. Postmark has two token types, and each operation in this reference states which one it needs.
| Token | Header | Used for |
|---|---|---|
| Server token | X-Postmark-Server-Token | Sending email and server-level resources: messages, bounces, templates, stats, webhooks, suppressions, message streams, inbound rules. Found on the API Tokens tab of a server. |
| Account token | X-Postmark-Account-Token | Account-level resources: servers, domains, sender signatures, template push, data removal. Found on the API Tokens tab of your account (Account Owner and Account Admins). |
Header names and values are case-insensitive. A missing or wrong token returns HTTP 401.
Send the Accept: application/json header on every request and Content-Type: application/json on requests with a body.
Test mode
Use POSTMARK_API_TEST as the server token to validate requests without sending any email.
Sending limits
- Maximum email size is 10 MB, including headers, bodies and Base64-encoded attachments.
TextBodyandHtmlBodycan each be up to 5 MB. - Maximum 50 recipients per message, counting To, Cc and Bcc together.
- Batch endpoints accept up to 500 messages and 50 MB of payload per call.
- The sender address must belong to a confirmed Sender Signature or verified domain.
Message streams
Email is sent through a message stream. Transactional streams (default ID outbound) carry one-to-one triggered email such as receipts and password resets. Broadcast streams carry bulk email such as newsletters. Select a stream with the MessageStream field; most endpoints default to outbound.
Dates and pagination
Collection endpoints use count and offset. Searches over messages and bounces return at most 10,000 records (count + offset ≤ 10,000); use fromdate and todate to retrieve more. Date-times without a time zone are interpreted as US Eastern Time.
HTTP status codes
| Status | Meaning |
|---|---|
| 200 | Success. For batch endpoints this does not mean every message succeeded; check each entry's ErrorCode. |
| 401 | Missing or incorrect API token. |
| 404 | The entity does not exist. |
| 413 | Payload too large (10 MB for an email, 50 MB for a batch). |
| 415 | Missing or wrong Content-Type/Accept headers. |
| 422 | The request is malformed or has invalid fields. The body contains an ErrorCode and Message. |
| 429 | Rate limit exceeded; slow down. |
| 500 | Postmark failed to process the request. |
| 503 | Planned maintenance. |
API error codes
Error responses have the form {"ErrorCode": 403, "Message": "Invalid request field(s): 'From'."}. The code is also returned in the X-PM-ApiErrorCode response header. Commonly encountered codes:
| Code | Meaning |
|---|---|
| 10 | Bad or missing API token, or wrong token type for the endpoint. |
| 300 | Send validation failed (invalid address, missing body, recipient or attachment limits). |
| 402 / 403 | Invalid JSON / invalid request field(s). |
| 406 | Inactive recipient (hard bounce, spam complaint or manual suppression). |
| 410 | More than 500 messages in a batch. |
| 1100-1131 | Template errors (not found, invalid alias, limits). |
| 1221-1241 | Message stream errors. |
| 1364 | Webhook verification failed; nothing was saved. |
The complete list is in the Postmark error code reference.
Webhooks
Webhook event payloads (delivery, bounce, spam complaint, open, click, subscription change) are documented as callbacks on the Create a webhook operation and as *WebhookPayload schemas. Postmark does not sign webhook requests; secure your endpoint with HTTP Basic Auth, custom headers and IP allowlisting.