Latest updates

API October 31, 2023

Changes to Email API validation – Action may be required

We're making some improvements to our API infrastructure and as a result, we're changing how we handle the validation of your API requests.

In the past, Postmark's email API has been pretty forgiving to requests that are passed incorrectly. In some cases, we've accepted invalid request headers and incorrectly passed JSON body key/value pairs—even if they didn't match our API documentation. Going forward, we'll start to reject invalid requests and return an error message instead.

So if you see Postmark return error messages to API requests that were previously accepted without issues, please double-check if your request is actually valid. We recommend using a tool such as JSONLint to check your request payloads for any obvious validation errors, and if that shows no issues then refer to our API documentation pages and make sure your request matches the schema(s) we are expecting.

Here are some common reasons why your request might be invalid.

Show details

Timeline

We’ll release the new API infrastructure on November 28th, 2023 but we’ll be running a set of blackout periods before where all traffic is sent over the new Email API infrastructure. Along with greyouts before where some traffic is sent to the new API infrastructure to help surface possible issues. Here’s what to expect:

Up until November 28th greyouts where a small subset of traffic is sent through the new infrastructure.
November 15th: First blackout period from 10:00am -12:00pm ET (2 hours)
November 15th: Second blackout period from 5:00pm - 7:00pm (2 hours)
November 28th: New API infrastructure is released for Email API.

What’s changing

There are two places where a request made to our Email API could be invalid:

Content-Type and Accept headers
If your request headers do not include "Accept: application/json" and "Content-Type: application/json", or these headers are set to different values such as "application/www-x-form-urlencoded", this will result in a 415 error status code.
JSON request body
Please make sure your request body is valid JSON and has the correct field types. For example:
- Array and object fields (such as Headers, Attachments and Metadata) should not be passed as strings. If no value is required, simply leave the field out (or provide an empty array/object.)
- JSON strings must be wrapped in double quotes. Single quotes are not valid JSON string wrappers and will result in an error
- Newlines are not valid within JSON, unless they are properly escaped (ie. “\n”). This is particularly relevant for HtmlBody and TextBody fields, which often contains newline characters
- The above would result in a 422 status code response from our API.

This applies to the following API endpoints:

https://api.postmarkapp.com/email/
https://api.postmarkapp.com/email/batch
https://api.postmarkapp.com/email/withTemplate
https://api.postmarkapp.com/email/batchwithTemplate

Here are some examples:

Invalid Headers

curl "https://api.postmarkapp.com/email/withTemplate" \
 -X POST \
 -H "Accept: application/json" \
 -H "Content-Type: application/www-x-form-urlencoded" \
 -H "X-Postmark-Server-Token: server token" \

Valid Headers

curl "https://api.postmarkapp.com/email/withTemplate" \
 -X POST \
 -H "Accept: application/json" \
 -H "Content-Type: application/json" \
 -H "X-Postmark-Server-Token: server token" \

Invalid JSON request body

{
…
"Headers":"",
…
}

Valid JSON Request Body


{
…
"Headers": [
 {
 "Name": "CUSTOM-HEADER",
 "Value": "value"
 }
 ],
…
}

Invalid HtmlBody with newlines

{
 "HtmlBody": "<html>
 <body>
 <div>This is not valid</div>
 </body>
 </html>"
}

Valid HtmlBody with newlines

{
 "HtmlBody": "<html>\n<body>\n<div>This is valid</div>\n</body>\n</html>"
}

What you need to do

For messages that are failing with a 415 response code, you’ll want to review the Accept and Content-Type request headers to ensure they match our documented headers for the Email API endpoint. If there is a header that is missing, or is not set to application/json, you’ll need to add or update them accordingly.

If you’re receiving a 422 “Invalid request” response, review our Email API endpoint documentation to ensure you’re passing the correct field types as documented.

If you have any questions or need any help troubleshooting issues, please let us know.