API Response Formats

Handling responses from the Postman API

HTTP Status Codes

Postman uses conventional API Responses Codes to indicate the success or failure of an API request.

Format of Successful Responses

All responses to successful requests to the Postman API will be returned in JSON format with a HTTP status code in the 2xx range. The response will contain information about the resources that are being acted on (e.g. creation, retrieval).

Sending messages is an asynchronous process. As such, a successful API request to our message sending endpoints simply mean the request has been made successfully. It does not mean that your message has been sent or delivered successfully. To check this, you should call the respective endpoints (email, SMS) to check the status of your message.

The following is an example of a JSON object received after sending an email via the this endpoint of our programmatic email API:

{
  "id": "42",
  "from": "Postman.gov.sg <donotreply@mail.postman.gov.sg>",
  "recipient": "hello@example.com",
  "params": {
    "body": "Hello World",
    "from": "Postman.gov.sg <donotreply@mail.postman.gov.sg>",
    "subject": "Hello World",
    "reply_to": "hello@example.com"
  },
  "attachments_metadata": [
    {
      "fileName": "example.pdf",
      "fileSize": 1240,
      "hash": "8743b52063cd84097a65d1633f5c74f5"
    }
  ],
  "status": "ACCEPTED",
  "error_code": null,
  "error_sub_type": null,
  "created_at": "2023-05-10T03:03:55.406Z",
  "updated_at": "2023-05-10T03:03:55.406Z",
  "accepted_at": "2023-05-10T03:03:55.406Z",
  "sent_at": null,
  "delivered_at": null,
  "opened_at": null,
  "classification": "FOR_ACTION",
  "tag": "hello world"
}

Format of Error Responses

For error responses (with non-2xx codes), the response will be in JSON format with these fields

{
  "code": "error code for this specific error type",
  "message": "human-readable explanation of the error and possibly the next step"
}

Ideally, most of our errors are expected to happen during development process for your system and to serve as guidelines for your developers. However, some might happen for your production system (for e.g. 429 rate_limit error), in which case, using the code field is a reliable way to programmatically handle those error flows. All error code(s) can be found in our Swagger documentation or under the respective sections of this guide.

Last updated