AuthSMTP API Access v1.01
NEW: We have a new version of the AuthSMTP web API thats supports message submission and is available as a BETA service to all users.
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)
- 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.
URL Format: https://secure.authsmtp.com/restful/basic_user/USER-ID
...will return a 'basic_user' XML object for the user requested which includes details about the account and current quota usage etc.
URL Format: https://secure.authsmtp.com/restful/ip_allocation/USER-ID
...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.
By default API access is NOT enabled - to enable it login to the Control Panel.
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.
You should ensure that your code is able to gracefully handle errors in not being able to transmit messages to our network. While we endeavour to provide maximum availability for our service there is always the possibility of connectivity or other technical issues beyond our (or your) control. Ideally error handling, logging, message queueing (with retry) and monitoring should all be considered.
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:
'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).
All date fields are in 'YYYY-MM-DD HH:MM:SS' format.
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/ )
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.
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.
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.