Overview

Endpoint URL #

The Postmark API is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method. We enforce TLS encryption by issuing requests via HTTPS.

https://api.postmarkapp.com

Authentication #

All requests to Postmark’s API require you to authenticate yourself to the service. In order to do this you must send the correct HTTP header with the correct API token. Postmark has two types of API tokens:

• Server Token — X-Postmark-Server-Token Used for requests that require server level privileges. Found from the API Tokens tab under your Postmark server. This token is accessible by Account Owners, Account Admins, and users who have Server Admin privileges on a server. 
• Account Token — X-Postmark-Account-Token Used for requests that require account level privileges. Found from the API Tokens tab of your Postmark account. This token is accessible by the Account Owner and Account Admins.
  

Each reference page for the different API endpoints will always specify which authentication header to use. The header name and value are case insensitive. In the case that you execute a request with wrong or missing headers, you will receive an HTTP Response 401 (Unauthorized).

Often when implementing your client library or when integrating an existing library into your application you may want to send test emails that don’t actually get delivered to the recipient. In most cases you just need to know if your data is valid. You can do this by passing the POSTMARK_API_TEST value in the X-Postmark-Server-Token header field.

HTTP response codes #

• 200 — Success Everything went smooth.
• 401 — Unauthorized Missing or incorrect API token in header.
• 404 — Entity doesn't exist You made a request for a resource/entity that does not exist. Please ensure the endpoint and ID you are requesting are correct.
• 413 — Payload Too Large The request exceeded Postmark's size limit of 10 MB for our Email API and 50 MB total payload size for our Batch Email API.
• 415 — Unsupported Media Type The API request is missing the expected request headers. Please review the documentation for the API endpoint to ensure the required request headers are passed.
• 422 — Unprocessable Entity Something with the request isn't quite right — malformed JSON or invalid fields, for example. The response body contains JSON with an API error code and a message with the details:
  {
   "ErrorCode": 403,
   "Message": "Invalid request field(s): 'From'."
  }
• 429 — Rate Limit Exceeded We have detected that you are making requests at a rate that exceeds acceptable use of the API. You should reduce the rate at which you query the API.
• 500 — Internal Server Error This is an issue with Postmark’s servers processing your request. In most cases the message is lost during the process, and we are notified so that we can investigate the issue.
• 503 — Service Unavailable During planned service outages, Postmark API services will return this HTTP response and associated JSON body.

API error codes #

When the Postmark API detects a problem with your request, it returns a JSON body with a numeric ErrorCode and a human-readable Message, and echoes the code in the X-PM-ApiErrorCode response header. Most input errors use HTTP 422, but some use a different status — for example, authentication failures return 401 and maintenance returns 503. Each code's status is listed in the HTTP column below. A single ErrorCode can cover several related messages.

{
  "ErrorCode": 403,
  "Message": "Invalid request field(s): 'From'."
}

The ErrorCode field can be used to programmatically detect the type of error. Here are the supported error codes: