Postmark
Postmark API

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

Fork in Postman

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.

TokenHeaderUsed for
Server tokenX-Postmark-Server-TokenSending 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 tokenX-Postmark-Account-TokenAccount-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. TextBody and HtmlBody can 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

StatusMeaning
200Success. For batch endpoints this does not mean every message succeeded; check each entry's ErrorCode.
401Missing or incorrect API token.
404The entity does not exist.
413Payload too large (10 MB for an email, 50 MB for a batch).
415Missing or wrong Content-Type/Accept headers.
422The request is malformed or has invalid fields. The body contains an ErrorCode and Message.
429Rate limit exceeded; slow down.
500Postmark failed to process the request.
503Planned 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:

CodeMeaning
10Bad or missing API token, or wrong token type for the endpoint.
300Send validation failed (invalid address, missing body, recipient or attachment limits).
402 / 403Invalid JSON / invalid request field(s).
406Inactive recipient (hard bounce, spam complaint or manual suppression).
410More than 500 messages in a batch.
1100-1131Template errors (not found, invalid alias, limits).
1221-1241Message stream errors.
1364Webhook 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.

Tags