Overview

Integration

User guide

API reference

Webhooks

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.
  • 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.