Overview

Integration

User guide

API reference

Webhooks

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 message isn’t quite right, this could be malformed JSON or incorrect fields. In this case, the response body contains JSON {ErrorCode: 405, Message: "details"} with an API error code and message containing details on what went wrong.
  • 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. If you have specific rate requirements, please contact support to request a rate increase.
  • 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 #

Whenever the Postmark server detects an input error it will return an HTTP 422 status code along with a JSON object containing error details:

{
  "ErrorCode": 405,
  "Message": "details"
}

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

  • 10 — Bad or missing API token Your request did not contain the correct API token in the header. Refer to the request’s API reference page to see which API token is required or learn more about authenticating with Postmark.
  • 11 - Multiple errors occurred: Multiple errors occurred. Inspect the Errors property on the response for more detailed information.
  • 12 - Resource not found: The item you are trying to access was not found.
  • 13 - Invalid pagination key: The pagination key provided in the request was invalid.
  • 100 — Maintenance The Postmark API is offline for maintenance.
  • 300 — Invalid email request Validation failed for the email request JSON data that you provided.
  • 400 — Sender Signature not found You’re trying to send email with a From address that doesn’t have a sender signature. Refer to your existing list of Sender Signatures or add a new one.
  • 401 — Sender signature not confirmed You’re trying to send email with a From address that doesn’t have a confirmed sender signature. You can resend the confirmation email on the Sender Signatures page.
  • 402 — Invalid JSON The JSON data you provided is syntactically incorrect. We recommend running your JSON through a validator before issuing another request.
  • 403 — Invalid request fields(s) - {FIELD_NAME} The JSON data you provided is invalid in some way. The {FIELD_NAME} references where the request is invalid. Refer to the request's API reference page to see a list of required JSON body parameters. If this has suddenly started to happen, please review our recent update.
  • 405 — Not allowed to send Your account has run out of credits. You can purchase more on the Credits page.
  • 406 — Inactive recipient You tried to send email to a recipient that has been marked as inactive. Inactive recipients have either generated a hard bounce or a spam complaint. In this case, only hard bounce recipients can be reactivated by searching for them on your server’s Activity page and clicking the “Reactivate” button.
  • 409 — JSON required Your HTTP request doesn’t have the Accept and Content-Type headers set to application/json.
  • 410 — Too many batch messages Your batched request contains more than 500 messages.
  • 411 — Forbidden attachment type The file type of the attachment isn’t allowed. Refer to our list on forbidden file types.
  • 412 — Account is Pending The account that is associated with the send request is still pending approval. While an account is pending approval, email recipients must have the same domain as the one found in the email's from address.
  • 413 — Account May Not Send The account that is associated with the send request is not approved for sending.
  • 500 — Sender signature query exception You provided invalid querystring parameters in your request. Refer to the Sender Signatures API reference for a list of accepted querystring parameters.
  • 501 — Sender Signature not found by id We couldn’t locate the Sender Signature you’re trying to manage from the id passed in.
  • 502 — No updated Sender Signature data received You didn’t pass in any valid updated Sender Signature data.
  • 503 — You cannot use a public domain You tried to create a Sender Signature with a public domain which isn’t allowed.
  • 504 — Sender Signature already exists You tried to create a Sender Signature that already exists on Postmark.
  • 505 — DKIM already scheduled for renewal The DKIM you tried to renew is already scheduled to be renewed.
  • 506 — This Sender Signature already confirmed The signature you tried to resend a confirmation to has already been confirmed by a user.
  • 507 — You do not own this Sender Signature This Sender Signature cannot be found using your credentials.
  • 510 — This domain was not found We couldn’t locate the Domain you’re trying to manage from the id passed in.
  • 511 — Invalid fields supplied You didn’t pass in any valid Domain data.
  • 512 — Domain already exists You tried to create a Domain that already exists on your account.
  • 513 — You do not own this Domain This Domain cannot be found using your credentials.
  • 514 — Name is a required field to create a Domain You must set the Name parameter to create a Domain.
  • 515 — Name field must be less than or equal to 255 characters The Name you have specified for this Domain is too long.
  • 516 — Name format is invalid The Name you have specified for this Domain is formatted incorrectly.
  • 520 — You are missing a required field to create a Sender Signature. When creating a Sender Signature, you must supply a value for Name and FromEmail.
  • 521 — A field in the Sender Signature request is too long. View the Message property of the response for details. ConfirmationPersonalNote has a max length of 400 characters.
  • 522 — Value for field is invalid. Value might be an invalid email address or domain. View the Message property of the response for details. ConfirmationPersonalNote must contain at least one non-whitespace character.
  • 600 — Server query exception You provided invalid querystring parameters in your request. Refer to the Servers API reference for a list of accepted querystring parameters.
  • 602 — Duplicate Inbound Domain The Inbound Domain you specified is already in use on Postmark.
  • 603 — Server name already exists You tried to create a Server name that already exists in your list.
  • 604 — You don’t have delete access You don’t have permission to delete Servers through the API. Please contact support if you wish to have this functionality.
  • 605 — Unable to delete Server We couldn’t delete this Server. Please contact support.
  • 606 — Invalid webhook URL The webhook URL you’re trying to use is invalid or contains an internal IP range.
  • 607 — Invalid Server color The server color you specified isn't supported. Please choose either Purple, Blue, Turqoise, Green, Red, Orange, Yellow, or Grey for server color.
  • 608 — Server name missing or invalid The Server name you provided is invalid or missing.
  • 609 — No updated Server data received You didn’t pass in any valid updated Server data.
  • 610 — Invalid MX record for Inbound Domain The Inbound Domain provided doesn’t have an MX record value of inbound.postmarkapp.com.
  • 611 — InboundSpamThreshold value is invalid. Please use a number between 0 and 30 in increments of 5.
  • 700 — Messages query exception You provided invalid querystring parameters in your request. Refer to the Messages API reference for a list of accepted querystring parameters.
  • 701 — Message doesn’t exist This message doesn’t exist.
  • 702 — Could not bypass this blocked inbound message, please contact support. There was a problem processing this bypass request. Please contact support to fix the issue.
  • 703 — Could not retry this failed inbound message, please contact support. There was a problem processing this retry request. Please contact support to fix the issue.
  • 800 — Trigger query exception You provided invalid querystring parameters in your request.
  • 809 — No trigger data received You didn’t provide JSON body parameters in your request.
     
  • 810 — This inbound rule already exists. You tried to add a rule that already exists for the server. Please choose a unique rule to add.
  • 811 — Unable to remove this inbound rule, please contact support. We weren't able to remove this rule from your server. Please contact support to resolve the issue.
  • 812 — This inbound rule was not found. The inbound rule you are trying to administer does not exist for this server.
  • 813 — Not a valid email address or domain. Please use a valid email address or valid domain to setup an inbound domain rule.
  • 900 — Stats query exception You provided invalid querystring parameters in your request. Refer to the Stats API reference for a list of accepted querystring parameters.
  • 1000 — Bounces query exception You provided invalid querystring parameters in your request. Refer to the Bounces API reference for a list of accepted querystring parameters.
  • 1001 — Bounce was not found. The BounceID or MessageID you are searching with is invalid.
  • 1002 — BounceID parameter required. You must supply a BounceID to get the bounce dump.
  • 1003 — Cannot activate bounce. Certain bounces and SPAM complaints cannot be activated by the user.
  • 1100 — Template query exception. The value of a GET parameter for the request is not valid.
  • 1101 — Template not found. The TemplateId,  LayoutTemplate, or Alias references a Template that does not exist, or is not associated with the Server specified for this request.
  • 1105 — Template limit would be exceeded. A Server may have up to 100 templates, processing this request would exceed this limit. Please contact support if you need more Templates within a Server.
  • 1109 — No Template data received. You didn’t provide JSON body parameters in your request. Refer to the Template API reference for more details on required parameters.
  • 1120 — A required Template field is missing. A required field is missing from the body of the POST request.
  • 1121 — Template field is too large. One of the values of the request's body exceeds our size restrictions for that field.
  • 1122 — A Templated field has been submitted that is invalid. One of the fields of the request body is invalid.
  • 1123 — A field was included in the request body that is not allowed. A field is included in the request that will be ignored, or is not applicable to the endpoint to which it has been sent.
  • 1125 — The template types don't match on the source and destination servers. The template alias is a layout on one server and a standard template on the other. The templates cannot share the same alias.
  • 1130 - The layout template cannot be deleted because it has dependent templates using it. A layout cannot be deleted when there are associated templates using the layout.
  • 1131 - The layout content placeholder must be present in the layout HTML and/or Text body exactly once. A single content placeholder is required for every layout. The content placeholder cannot be present in a standard template.
  • 1221 - The 'MessageStreamType' associated with this request was invalid. Please make sure to interact with a Message Stream that supports the function you're trying (For example, not trying to send an email through an Inbound Stream).
  • 1222 - A valid 'ID' must be provided. Postmark was unable to find a Message Stream with the provided Message Stream ID that was used with the API Token
  • 1223 - A valid 'Name' must be provided. A Stream name cannot be null or whitespace.
     
  • 1224 - The 'Name' is too long, it is limited to 100 characters. Please create a shorter name.
  • 1225 - You have reached the maximum number of message streams for this server. A stream can have up to 10 Message Streams. Please contact support if you need more Message Streams.
  • 1226 - The message stream for the provided 'ID' was not found. Postmark was unable to find a Message Stream with the provided Message Stream ID that was used with the API Token.
  • 1227 - The 'ID' must be a non-empty string starting with a letter of the English alphabet. It is limited to lowercase letters of the English alphabet, numbers, and '-', '_' characters. It is limited to a length of 30 characters.
  • 1228 - A server can only have one inbound stream. If more Inbound Streams are needed, please create a new Server.
  • 1229 - You cannot archive the default transactional and inbound streams. The default Transaction and Inbound streams cannot be deleted.
  • 1230 - The 'ID' provided already exists for this server. ID's must be unique.
  • 1231 - The 'Description' is too long, it is limited to 1000 characters. Please create a shorter description.
  • 1232 - You cannot unarchive this message stream anymore. The Message Stream is either deleted is no longer archived.
  • 1233 - The 'ID' must not start with the 'pm-' prefix. It is not possible to create Message Streams that start with 'pm-'.
  • 1234 - The 'Description' must not contain HTML tags. The characters '<' and '>' are not allowed.
  • 1235 - The 'MessageStream' provided does not exist on this server. Postmark was unable to find a Message Stream with the provided Message Stream that was used with the API Token.
  • 1236 - Sending is not supported on the supplied 'MessageStream'. Sending is not possible with Inbound Message Streams.
  • 1237 - This 'ID' is reserved. The ID all is reserved, please use a different ID.
  • 1300 - Invalid Data Removal request. Refer to the Data Removal API reference.
  • 1301 - Invalid ID. Missing or incorrect data removal request ID.
  • 1302 - You don’t have Data Removal request access. You don’t have permission to process or review data removal requests through the API. Please contact support if you wish to have this functionality.