API Overview

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.

Legacy API: This describes the version 1.0 API which is supported for compatibility reasons. New applications or integrations should make use of the current version.

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

UID Values

Many API calls support a user-specified ID, or UID, which is a completely arbitrary string value that that can be used as a reference for subsequent calls. Note that these must be unique per project or per account depending on context.

If a UID is not supplied, a UUID or SHA2 hash of the originating request may be generated and applied.

Example Use Cases

When sending a message it may be useful to encode information in the UID in a human-readable form. This can make diagnostics easier. For example, a daily mailing might encode as mailing-intro:20190401.001 where 001 represents a batch sequence.

These values can be used to verify that a particular API call was received and processed correctly. For example, a send_message call could be followed up with a get_message_transmissions a few hours later to download a delivery report.

Choosing a UID value that is meaningful to both you and your application can make integration with PostageApp very straightforward.

Responses

Responses will typically look something like this:

{
  "response" : {
    "uid" : "RESPONSE_UID",
    "status" : "ok"
  },
  "data" : {
    "message" : {
        "id" : "MESSAGE_ID"
    }
  }
}

An error would look like this:

{ "response" : {
    "uid" : "RESPONSE_UID",
    "status" : "error_code",
    "message" : "Message text describing 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."
  }
}