AuthSMTP API Access v1.01

API Overview

This API is designed to provide remote access to your account details and usage summary. It aims to be a RESTful web service that uses:

  • HTTP (over SSL - i.e. HTTPS)
  • XML
  • HTTP GET/PUT/POST/DELETE

For security the AuthSMTP API can only be accessed over HTTPS - and requires a separate API password to be assigned to your account.

API Functions

basic_user

URL Format: https://secure.authsmtp.com/restful/basic_user/USER-ID

Example: https://secure.authsmtp.com/restful/basic_user/aa12345

...will return a 'basic_user' XML object for the user requested which includes details about the account and current quota usage etc.

ip_allocation

URL Format: https://secure.authsmtp.com/restful/ip_allocation/USER-ID

Example: https://secure.authsmtp.com/restful/ip_allocation/aa12345

...will return a 'ip_allocation' XML object for the user requested which includes the function version and list of IP addresses dedicated to your account. If no IP addresses are allocated to the account it will return an XML error object.

Getting Started

By default API access is NOT enabled - to enable it login to the Control Panel.

Rate Limiting

There is a rate limit on API calls - do not make more than 1 API request every 20 seconds.

If you exceed the query rate limit - your request will return an XML error object indicating you have been rate limited.

API Responses

Your API request will generate:

  • An HTTP response (e.g. '401 Not Authorized', or '200 OK').

If the HTTP response is '200 OK' - it will additionally generate:

  • Either An XML error object, or an XML data object.

Typical HTTP responses are:

  • 200 'OK' (expect an XML object in the reply).
  • 401 'Not Authorized' (i.e. no / wrong password was provided).
  • 404 'Not found' (an attempt to call a non-existant function URL was made).
  • 500 'Internal Error' (an error occurred internal to our system while trying process the request).

You can only request your own user_id information via this call - unless you have the user_id and API passwords for other accounts.

v1.01 'basic_user' XML Object returned in response to https://secure.authsmtp.com/restful/basic_user/:


v1.00 'ip_allocation' XML Object returned in response to https://secure.authsmtp.com/restful/ip_allocation/:


v1.00 'error' XML Object returned in response to any non HTTP type error will be:


Field Formats

'version' is the object version

Minor (compatible changes) are reflected by bumping the .xx part, e.g. '1.00' and '1.01' should be compatible (for example - fields have been added only).

Major changes (such as changing the structure, nesting more fields - or changing the names / values for fields) will be reflected with a new Major version number, i.e. the differences between '1.04' and '2.00' would usually require parsing code changes. We will try to keep changes compatible, but obviously can't guarantee this in the future.

A request for data will always return it in the current / highest version number available (i.e. you cannot request data in older formats).

Date Fields

All date fields are in 'YYYY-MM-DD HH:MM:SS' format.

Quantity Fields

All 'quantity' fields (e.g. maximum message size, messages sent etc.) are in plain numeric format (no commas, no decimal places).

Quantity fields can be large - be careful your system copes with large quantities (i.e. >4 billion for some account types). For that reason the 'basic_user' object includes the remaining data / message quotas again, as plain numeric fields.

'next_reset' is the Date / Time the quota will next reset

This can be 'in the past' - if an account is not currently sending mail. If the 'next_reset' is in the past it indicates the quota will reset immediately the next time mail is sent.

'current_datetime' is the current Date / Time on the server

The servers currently track United Kingdom time, this is either UTC, or UTC +1 (aka 'BST' - British Summer Time). This field includes the prevailing offset from UTC, e.g. '+0100' on the end.

Accessing the Data

You cannot use this API with a regular browser. The browser will not provide the username, and password details to the request (in addition the server will not supply the 'WWW-Authenticate' header back to the browser to get it to prompt for these details). Browsers tend to cache results (including errors) - and are not suitable for accessing the API directly.

If you need web browser access to the data - please use the Control Panel (i.e. http://www.authsmtp.com/login/ )

Example code

PHP with 'basic_user' function

The following example PHP code will retrieve the current 'basic user' information for 'myUserID' (presuming this account has been setup with API access) and will display their account information. It is designed to be run from a web page, but can also be used as the basis for command line tools.


PHP with 'ip_allocation' function

The following example PHP code will retrieve the current 'ip_allocation' information for 'myUserID' (presuming this account has been setup with API access) and will display their dedicated IP addresses. It is designed to be run from a web page, but can also be used as the basis for command line tools.


PERL with 'basic_user' function

Same example, but in perl - this is designed to be run from the command line.


C# Example

Note: Older versions of .NET (< 4.5.1) do not consider TLS v1.1 or v1.2 as a viable protocol so will not use them by default - we only support those protocols for the API. This example includes code to force their use.


Ruby Example

This script requires Ruby itself and 'Curb' (Ruby bindings for lib curl).

It will connect to the API, retrieve the data and output the XML to the browser.


If you have any questions or problems with the API please contact us.