Authentication

Requests made to the API are protected with HTTP Basic authentication. To properly authenticate with the API, you must use the API key for the account you are making calls for. This could be a single master account or a sub-account of an agency. Requests that are not properly authenticated will return a 401 error code.

curl uses the -u flag to pass basic authentication credentials (adding a colon after your API key will prevent it from asking for a password). Note that this call must be made via HTTPS.

curl https://api.postalytics.com/api/v1/templates \
  -u 12345EF4-3AEF-7ADE-A468-9D51756E5D32:

If the user/password combination you pass in fails, this is the body of the HTTP 401 message that you will see:

{
  "error": {
    "message": "Invalid API key. User authentication failed",
    "status_code": 401
  }
}

• message: A human-readable message with more details about the error.
• status_code: A conventional HTTP status code.

Postalytics uses RESTful HTTP response codes to indicate the success or failure of an API request. In general:

• 2xx: Indicates success.
• 4xx: Indicates an input error.
• 5xx: Indicates an error on Postalytics' side.

Postalytics enforces a rate limit of 3 requests/second or 180 requests/minute for each API key user. The rate limit ensures the system is not overloaded with too many requests from a single user at once. If the rate limit is exceeded, subsequent calls within that window will return an HTTP 429 error.