General

The API works with the network protocol SOAP (Simple Object Access Protocol). SOAP libraries can be found in many modern programming languages such as PHP, Python, Java and C++. SOAP therefore provides a good basis for simple cross-language communication. The basis for SOAP is the WSDL file, in which all functions and parameters of the API are described. The WSDL file is provided in XML format and can be read by many editors (e.g. Aptana).

API Key

Introduction

In order to communicate with the API, you need an API key and your user ID. Using this data, you will be clearly identified to work with the API and have access to your account.

To create your API key and to display your User ID, log into your account and click on API at the very bottom in the footer.

Then click on the button Generate API Key.

t

Client set up (example: PHP5)

Many modern programming languages offer existing libraries with which you can use quickly and easily use SOAP functions.

<?php $client = new SoapClient("http://api.sendcockpit.com/server.php?wsdl"); class SOAPAuth{ public $userid; public $apikey; public $version; public $mode; public function __construct($userid, $apikey, $version, $mode = 'test') { $this->userid = $userid;
        $this->apikey = $apikey;
        $this->version = $version;
        $this->mode = $mode;
    }
}
 
 
$auth = new SOAPAuth('User ID','API Key','1.0','test');
 
$header = new SOAPHeader('sendcockpit', 'validate', $auth);
 
$client->__setSoapHeaders($header);
 
try{
    //get all subscriber lists from account
    $response=$client->apiGetList();
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}
 
?>

API constants

Configure your client as follows

Authentication

Authentication in the API is done through the SOAP header. The name of the header is “validate”. An object containing the API key, the user ID, the API version, and the API mode as properties is passed to the header. Failed authentication returns an error message. Authentication must be performed with each function call.

PHP5 example: SOAP Header

class SOAPAuth{
 public $userid;
 public $apikey;
 public $version;

 public function __construct($userid, $apikey, $version, $mode = 'test'){
 $this->userid = $userid;
 $this->apikey = $apikey;
 $this->version = $version;
 $this->mode = $mode;
 }
}

$auth = new SOAPAuth('1234567','API Key','1.0','test');
$header = new SOAPHeader('sendcockpit', 'validate', $auth);

Input values

Most functions expect input parameters. All parameters (also single parameters) are passed as a list to the function. For example, if all subscribers are queried for a subscriber list, the function parameters look like the following.

PHP5 example

$parameter = array(
 'listID' => 123456
);

$response=$client->apiGetSubscriber($parameter);

The data type of a parameter can be found in the function description. You can also refer to the description to learn how large the data may be, and whether it is mandatory. The structure of complex data types is described together with the respective parameter lists.

Parameter lists always have a maximum size for input and return values. Should the transmitted list be larger than its maximum as specified in the description, it must be queried by means of a loop. For this purpose, the parameters start and count are available in each function. The parameter start defines at what point you want to start the query from the database, and count specifies how many records are to be transferred from start.

PHP5 example: return 100 subscribers from position 500

$parameter = array(
 'listID' => 123456,
 'start' => 500,
 'count' => 100,
);

$response=$client->apiGetSubscriber($parameter);

Return values

The interface provides return values in a stdClass object. If you are not familiar with this format, you can cast the object – for example using PHP – into an associative array.

The following example shows a stdClass Object, how to access a single element, and how you can cast the object and treated it as an array.

PHP5 Example: Accessing a single element > casting into an array

[subsriberResponse] => Array
(
 [0] => stdClass Object
 (
 [subscriberID] => 123456789

 [subscriberEmail] => joe.smith@example.com
 )
 [...]
)

//Output as a stdClass Object

echo $subsriberResponse[0]->subscriberID;

//Cast and output as an array

$subsriberResponse = (array)$subscriberResponse;
echo $subsriberResponse[0]['subscriberID'];