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.

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.

Error Handling

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.

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

// CODE REQUIREMENTS: CURL, SimpleXML

// Do not keep plain text passwords in the source .php file - this is purely for example, consider
// keeping them in a config file - or at least out of 'reach' of httpd.
$username = 'myUserID';
$password = 'myAPIpassword';

// Define connection URL
$base = 'https://secure.authsmtp.com/restful/basic_user';

// Initialize CURL to handle the request
$c = curl_init( $base.'/'.$username );
//$c = curl_init( $base.'/' );
if( $c == false ){
echo( "Error initializing CURL.n" ); exit();
}

// Set CURL options
curl_setopt( $c, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt( $c, CURLOPT_RETURNTRANSFER, true );
curl_setopt( $c, CURLOPT_SSL_VERIFYPEER, false );
curl_setopt( $c, CURLOPT_FOLLOWLOCATION, 1 );
curl_setopt( $c, CURLOPT_USERPWD, $username.':'.$password );

// Send the request
$res = curl_exec( $c );
if( $res === false ){
echo( "Connection failed.n" ); exit();
}

// Handle response
$tmp = curl_getinfo( $c );
$res_http = $tmp['http_code'];
curl_close( $c );

if( $res_http != 200 ){
echo( "An error occurred ($res_http) - full response is: $res " );
exit();
}

$data = new SimpleXMLElement( $res );

// If there is an error output to page
if( !empty( $data->error ) ){
echo( "An error occurred. " );
echo( $data->error->short." " );
echo( $data->error->verbose." " );
exit();
}

// Output the results
echo( "User ID: ".$data->basic_user->user_id." " );
echo( "Account Type: ".$data->basic_user->account_type." " );
echo( "Expires: ".$data->basic_user->expires." " );
echo( "Message Limit: ".$data->basic_user->messages_limit." " );
echo( "Data Limit: ".$data->basic_user->data_limit." " );
echo( "Messages Sent: ".$data->basic_user->messages_sent." " );
echo( "Data Sent: ".$data->basic_user->data_sent." " );
echo( "Next Reset: ".$data->basic_user->next_reset." " );
echo( "From Addresses Used: ".$data->basic_user->from_address_used." " );
echo( "Maximum Message Size: ".$data->basic_user->maximum_message_size." " );
echo( "Remaining Messages: ".$data->basic_user->messages_remaining." " );
echo( "Remaining Data: ".$data->basic_user->data_remaining." " );

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.

<?php

// CODE REQUIREMENTS: CURL, SimpleXML

// Do not keep plain text passwords in the source .php file - this is purely for example, consider
// keeping them in a config file - or at least out of 'reach' of httpd.
$username = 'xxxxxxxxx'; // ACTION REQUIRED - Set your username
$password = 'xxxxxxxx'; // ACTION REQUIRED - Set your API password

// Define connection URL
$base = 'https://secure.authsmtp.com/restful/ip_allocation';

// Initialize CURL to handle the request
$c = curl_init( $base.'/'.$username );
//$c = curl_init( $base.'/' );
if( $c == false ){
echo( "Error initializing CURL.n" ); exit();
}

// Send the request
$res = curl_exec( $c );
if( $res === false ){
echo( "Connection failed.n" ); exit();
}

// Handle response
$tmp = curl_getinfo( $c );
$res_http = $tmp['http_code'];
curl_close( $c );

if( $res_http != 200 ){
echo( "An error occurred ($res_http) - full response is: $res " );
exit();
}

$data = new SimpleXMLElement( $res );

// If there is an error output to page
if( !empty( $data->error ) ){
echo( "An error occurred. " );
echo( $data->error->short." " );
echo( $data->error->verbose." " );
exit();
}

// Output the results
foreach($data->ip_allocation->ip_address->children() as $ip){
echo( "IP Address: ".$ip." " );
}
?>

PERL with 'basic_user' function

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

#!/usr/local/bin/perl

# CODE REQUIREMENTS: XML::Simple and WWW::Curl

use strict;
use warnings;
use WWW::Curl::Easy;

use XML::Simple;
use Data::Dumper;

use constant false => 0;
use constant true => 1;

# Do not keep plain text passwords in source unless you're aware of the consequences, 
# you might want to consider keeping them in a 'config' type file
my $username = 'xxxxxxxxx'; // ACTION REQUIRED - Set your username
my $password = 'xxxxxxxxx'; // ACTION REQUIRED - Set your API password

# Define connection URL
my $base = 'https://secure.authsmtp.com/restful/basic_user';

my $curl = WWW::Curl::Easy->new;

# Set CURL options
$curl->setopt( CURLOPT_URL, $base.'/'.$username );
$curl->setopt( CURLOPT_CONNECTTIMEOUT, 30 );
$curl->setopt( CURLOPT_SSL_VERIFYPEER, false );
$curl->setopt( CURLOPT_FOLLOWLOCATION, false );
$curl->setopt( CURLOPT_USERPWD, $username . ':' . $password );

my $http_return;
$curl->setopt( CURLOPT_WRITEDATA, $http_return );

# Send the request
my $ret = $curl->perform;

# Handle response
if( $ret != 0 ){
# Error code, type of error, error message
print("An error happened: $ret ".$curl->strerror( $ret )."".$curl->errbuf."n");
exit
}

my $http_return_code = $curl->getinfo( CURLINFO_HTTP_CODE );

# See if we got a 200 OK or not
if( $http_return_code != 200 ){
print( "An error occurred - HTTP Response Code $http_return_code - output was:n" );
print( "$http_return" );
exit;
}

# If we got 200 OK we expect an XML object back at this point
my $xml = new XML::Simple;

my $data = $xml->XMLin( $http_return );

# If there is an error output to page
if( defined( $data->{error} ) ){
print( "An XML error occurred" );
print( " Short: $data->{error}->{short}n" );
print( "Verbose: $data->{error}->{verbose}n" );
exit;
}

# If we got a 200 response (OK) and not an XML error object output results to page

print( "User ID: $data->{basic_user}->{user_id}n" );
print( "Account Type: $data->{basic_user}->{account_type}n" );
print( "Expires: $data->{basic_user}->{expires}n" );
print( "Message Limit: $data->{basic_user}->{messages_limit}n" );
print( "Data Limit: $data->{basic_user}->{data_limit}n" );
print( "Messages Sent: $data->{basic_user}->{messages_sent}n" );
print( "Data Sent: $data->{basic_user}->{data_sent}n" );
print( "Next Reset: $data->{basic_user}->{next_reset}n" );
print( "From Addresses Used: $data->{basic_user}->{from_address_used}n" );
print( "Maximum Message Size: $data->{basic_user}->{maximum_message_size}n" );
print( "Remaining Messages: $data->{basic_user}->{messages_remaining}n" );
print( "Remaining Data: $data->{basic_user}->{data_remaining}n" );

print( "n" );

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.

using System;

using System.IO;
using System.Text;

using System.Net;
using System.Security.Cryptography.X509Certificates;
using System.Net.Security;

namespace ConsoleApplication1{

public class GetStuff
	{

public static void Main()
		{

string Username = "xxxxxxxx"; // ACTION REQUIRED - Set your username
			string Password = "xxxxxxxx"; // ACTION REQUIRED - Set your API password

WebRequest request = WebRequest.Create( "https://secure.authsmtp.com/restful/basic_user/" + Username );
			request.Proxy = null;

// We could use NetworkCredential/CredentialCache but this does not send the credentials on the
			// first request - even if 'PreAuthenticate' is set, so instead we manually add authorisation
			// headers to the request...
			string plaintext = String.Format( "{0}:{1}", Username, Password );
			byte[] encoded = Encoding.ASCII.GetBytes( plaintext );
			string base64 = Convert.ToBase64String( encoded );
			string authorization = String.Concat( "Basic ", base64 );
			request.Headers.Add( "Authorization", authorization );

// This sets a callback function for validating the SSL cert. It's beyond the scope of this
			// example code to do this - so our callback just returns "true" - this will accept *any*
			// certificate.
			ServicePointManager.ServerCertificateValidationCallback += new System.Net.Security.RemoteCertificateValidationCallback(ValidateServerCertificate);

// By default (in .NET <= 4.5) the webrequest will use protocols like SSL2, SSL3 and TLS1.0 which are now deprecated.
			// TLS1.1 or TLS1.2 are the only ones that are secure.
			// We force TLS1.1 (aka '.Tls11') for this request.
			ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls11;

HttpWebResponse response = (HttpWebResponse)request.GetResponse();
			Stream dataStream = response.GetResponseStream();
			StreamReader reader = new StreamReader(dataStream);
			string responseFromServer = reader.ReadToEnd();

Console.WriteLine( responseFromServer );

// Wait for 'Enter' to avoid the window closing if we're running this from the IDE
			Console.ReadLine();

}

// Actual Cert Verification Callback - simply return 'true' - Change this to do proper cert validation if you need it (recommended)
		public static bool ValidateServerCertificate(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors){ return true; }

}

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.