If you're not a big coder, and you're looking to integrate Benchmark with your current CMS or another program, check our Plugins & Integrations Directory page first to see if someone has already released code for your system.
All calls made to the Benchmark Email API require the user to have an account with Benchmark Email. You can sign up now to get a free trial account.
If the user's account is expired or deactivated, access to certain functions will be restricted.
The API is free to use.
The current API version is located at:
http://api.benchmarkemail.com/1.3
The APIs are currently in XML-RPC.
We recommend using the following packages
All API calls require that the user be associated with an active, authenticated session. The login() function is used to authenticate the user and generate a token for the session. This token is to be used on every subsequent API call.
The token is used to identify the authenticated user. You then no longer need to supply the login / password with each call. To get the list for all active tokens for a user use the getToken method. The token can be saved in any variable and be used for future references.
This example is written in PHP and requires PEAR XML-RPC installed.
<?php
/**
*
* This Example shows how to authenticate a user using XML-RPC.
* Note that we are using the PEAR XML-RPC client and recommend others do as well.
*/
require_once 'XML/RPC2/Client.php';
// Account Settings
$USERNAME='myusername';
$PASSWORD='mypassword';
$API_URL='http://api.benchmarkemail.com/1.0';
try
{
// Create the XML RPC Object
$client=XML_RPC2_Client::create($API_URL);
// Authenticate the user
$token=$client->login($USERNAME, $PASSWORD);
// Print the token
echo "Your Token is :" . $token;
}catch (XML_RPC2_FaultException $e){
echo "ERROR:" . $e->getFaultString() ."(" . $e->getFaultCode(). ")";
}
?>
In case you want to retrieve records which match certain criteria, you can use filters. The filter will compare the given value to the field defined for filter in the API method to evaluate the records to return. In case the filter is set to blank, all results would be returned.
The results of the read are split into virtual pages. The number of records in each page is determined by the pageSize parameter. The pageNumber parameter determines the starting position of the records to return. The pageNumber starts from 1. For e.g. if a certain function returns 1500 records and the pageSize is set to 100, there would be 15 pages ( 1500 / 100 ) available. To retrieve records from the 1000 position, the pageNumber would have to be set to 10.
You determine the order of the result by providing the orderBy parameter. This parameter would sort the result based on the given column. The value for the parameter would vary in different functions. By default, the result would be sorted from lowest to highest. To reverse this, you can use the sortOrder parameter. If you provide the value of "desc", the resuls would be sorted from highest to lowest.
This example is written in PHP and requires PEAR XML-RPC installed.
<?php
/**
*
* This Example shows how to authenticate a user using XML-RPC.
* Note that we are using the PEAR XML-RPC client and recommend others do as well.
*/
require_once 'XML/RPC2/Client.php';
// Account Settings
$USERNAME='myusername';
$PASSWORD='mypassword';
$API_URL='http://api.benchmarkemail.com/1.0';
try
{
// Create the XML RPC Object
$client=XML_RPC2_Client::create($API_URL);
// Authenticate the user
$TOKEN=$client->login($USERNAME, $PASSWORD);
// Fetch the first 10 Emails where the name contains "April" sorted on the last modified date,
// recent ones appearing first
$RECORDS=$client->emailGet($TOKEN, "April", 1, 10, "date", "1");
print_r($RECORDS);
// Fetch the next 10 Emails
$RECORDS=$client->emailGet($TOKEN, "April", 2, 10, "date", "1");
print_r($RECORDS);
}catch (XML_RPC2_FaultException $e){
echo "ERROR:" . $e->getFaultString() ."(" . $e->getFaultCode(). ")";
}
?>
For inserts, the maximum number of objects that can be specified is 1000 per method call.
For updates, please specify the values which are not specified as optional. In case you have not specified the value for the key field, the update would fail.
The return of a write query will include the id of the object (if found/given), a boolean indicating success/failure, a boolean indicating a new object was created, and an array of errors (if necessary). The return will contain results for objects in the same order as the objects were given. Thus, a client can rely on position in the return array for mapping input to errors for cases where an id is not specified.
there are plenty of PHP XML-RPC libraries, classes, etc. out there, however we're going to recommend one : the PEAR XML-RPC2 package. Install it via your system's PEAR facility. And don't let the age of it worry you - it might be a little old and under-maintained, but it works. It's also the package we use internally and test with constantly.
