API Overview

PostageApp has a simple JSON-based API that any application can use. All methods are done via HTTPS POST.

All authentication is via an API key sent as part of the payload.

There are two kinds of key: An account-level API key is used to alter the configuration of the account, create projects, and setup mailboxes, and a project-level API key is used to send mail and follow-up on those events.

JSON Content Type

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

curl -v \
    -X POST \
    -d '{ "api_key" : "PROJECT API KEY" }' \
    https://api.postageapp.com/v.1.1/get_account_info

The content type is assumed to be UTF-8 encoded JSON supplied as the POST body. An HTTP error and corresponding JSON message are returned if this is not the case, or if the JSON payload cannot be processed because of a syntax error, unexpected character encoding, or some other issue.

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.

Example 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."
  }
}

Version 1.0 (Legacy API)

The original version 1.0 API documentation is still available as that API is supported for legacy reasons and may be present in older integrations.