The PostageApp API uses many of the same standards as other APIs you may be familiar with, as all requests are simple POST requests that accept and return JSON responses. All authentication is via an API key, which is provided for you with each project.

JSON Content Type

When making a request to the API be sure to set the Content-Type of any POST request to application/json to properly identify the payload type.

An easy example using curl that you can drop into a terminal that gives account information when successfully submitted:

curl -v \
    -X POST \
    -H "Content-type: application/json" \
    -d '{ "api_key" : "PROJECT API KEY" }' \
    https://api.postageapp.com/v.1.0/get_account_info.json

Responses

All responses will typically look something like this:

{ "response" : {
    "uid" : "ResponseUID goes here",
    "status" : "ok"
  },
  "data" : {
    "message" : {
        "id" : "DataID goes here"
    }
  }
}

An error would look like this:

{ "response" : {
    "uid" : "ResponseUID goes here",
    "status" : "Error of the API call",
    "message" : "Message of the error"
  }
}

There are several types of errors that may result from using any of the API endpoints.

Error 401 Unauthorized

This indicates that the API key provided is no longer active.

{
  "response" : {
    "status" : "unauthorized",
    "message" : "Invalid or inactive account API key used."
  }
}

Error 406 Invalid JSON

This error results when the JSON payload sent in cannot be decoded. This is typically because the JSON string is incomplete or has syntax errors. Testing with a JSON lint tool can help identify any potential problems.

{
  "response" : {
    "status" : "invalid_json",
    "message" : "The posted content is not valid JSON."
  }
}

Error 406 Invalid UTF8

This error results when an invalid UTF8 character has been detected. This often occurs when sending JSON data using a non-UTF-8 encoding by accident, or from having bad UTF-8 data injected into a field. Ensuring that the data is actually UTF-8 clean can fix this.

{
  "response" : {
    "status" : "invalid_utf8",
    "message" : "The posted content is not encoded in UTF8 or contains invalid characters. Error detected at byte 10."
  }
}

Error 406 Call Error

This error occurs when there was an unexpected error during the preparation of the request such as encountering an array in the JSON structure where a string value was expected, or vice-versa.

{
  "response" : {
    "status" : "call_error",
    "message" : "The posted content is not valid JSON."
  }
}

Error 409 Conflict

This indicates a mis-match on the requested API version. Check the /v/ prefix on the API call to be sure it meets expectations.

{
  "response" : {
    "status" : "conflict",
    "message" : "Invalid API version."
  }
}

Error 423 Locked

This indicates the API key or the account associated with it has been disabled.

{
  "response" : {
    "status" : "locked",
    "message" : "The specified API key is not valid."
  }
}