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 recommend using SSL encryption by issuing requests through HTTPS, however it’s not enforced.

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. This token can be found on the Credentials tab under your Postmark server.
  • Account Token — X-Postmark-Account-Token Used for requests that require account level privileges. This token is only accessible by the account owner, and can be found on the Account tab of your Postmark account.

Each reference page for the different API endpoints will always specifiy 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.
  • 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.
  • 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.
  • 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 — Incompatible JSON The JSON data you provided is syntactically correct, but still doesn’t contain the fields we expect. Refer to the request's API reference page to see a list of required JSON body parameters.
  • 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 Damain.
  • 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.
  • 522 — Value for field is invalid. Value might be an invalid email address or domain. View the Message property of the response for details.
  • 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.
  • 601 — Server does not exist You tried to manage a server that doesn’t exist with your credentials.
  • 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 incrememts 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. Refer to the Triggers API reference for a list of accepted querystring parameters.
  • 801 — Trigger for this tag doesn’t exist You tried to manage a trigger that doesn’t exist in your server.
  • 803 — Tag with this name already has trigger associated with it The server already has a trigger associated with the Tag name you provided.
  • 808 — Name to match is missing MatchName property is required in request JSON body. Refer to the Triggers API reference for more details.
  • 809 — No trigger data received You didn’t provide JSON body parameters in your request. Refer to the Triggers API reference for more details on required parameters.
  • 810 — This inbound rule already exists. You tried to add a rule that already exists for thie 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 — TemplateId not found. The TemplateId 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 300 active templates, processing this request would exceed this limit.
  • 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.