Troubleshooting 422 Unprocessable Entity Errors

In the world of APIs, a 422 Unprocessable Entity error is one of the most common responses you will encounter. Unlike a 401 error (which means your API token is wrong) or a 404 error (which means the endpoint doesn't exist), a 422 error means Postmark successfully received your request, but the data inside that request is invalid or missing required information.

Think of it as a form being submitted with a missing required field or a poorly formatted phone number; the server understands what you are trying to do, but it cannot proceed with the data provided.

How to identify the cause

When Postmark returns a 422 status code, the API response body contains a JSON object with a specific ErrorCode and a Message. This message is the key to resolving the issue quickly.

Example Error Response:

JSON

{
  "ErrorCode": 300,
  "Message": "Invalid 'From' address: 'sender@example.com' is not a verified sender signature."
}

Common reasons for 422 errors

Most 422 errors fall into one of four categories:

1. Unverified Sender Signatures

You cannot send email from an address or domain that hasn't been verified in your Postmark account.

The fix: Ensure the email address in your From field matches a verified Sender Signature or belongs to a verified Domain in your dashboard.

2. Missing Required Fields

Every request to the /email endpoint must contain:

From: A verified sender.
To: At least one recipient.
Subject: A subject line (even if it's short).
HtmlBody or TextBody: At least one version of your message content.

3. Invalid Email Formatting

If an email address is missing an @ symbol, has a trailing space, or contains invalid characters, the API will reject the entire request.

The fix: Use a library to validate email addresses in your application before sending them to the Postmark API.

4. Template Model Mismatches

If you are using the /email/withTemplate endpoint, a 422 error often occurs if:

The TemplateId or TemplateAlias is incorrect.
The TemplateModel is missing a required variable that your template needs to render correctly.

Debugging steps for developers

If you are seeing 422 errors in your logs, follow these steps to narrow down the cause:

Log the full response body: Don't just log the 422 status code. Ensure your application logs the JSON response from Postmark, as it contains the specific ErrorCode.
Check the Message Stream: Ensure you are sending to the correct stream. For example, if you try to send a broadcast email through a transactional stream (or vice versa), the request may be rejected.
Validate your JSON: Use a tool like JSONLint to ensure your payload is properly formatted. A missing comma or unclosed bracket can lead to processing errors.
Test with cURL: Strip away your application code and try sending a manual request using cURL. If the cURL request works, the issue likely lies in how your application is constructing the data.

Summary of 422 Error Codes

Here are a few specific codes you might see in a 422 response:

ErrorCode 300: Invalid 'From' address.
ErrorCode 402: Invalid JSON.
ErrorCode 1101: Template not found.
ErrorCode 1109: Template model is missing a required property.

For a complete list of all possible error codes and their meanings, please visit our official API documentation: https://postmarkapp.com/developer/api/overview#error-codes