Introduction
Ruby Gem
An official Ruby Gem for the Clever Elements API can be found here: https://rubygems.org/gems/cleverelements
PHP wrapper
Data types
Each PHP5 example
subscriberList
$subscriber[0] = array( 'listID' => '3679', 'email' => 'joe.smith@example.com', 'customFields' => array( 0 => array( 'customFieldID' => '13118', 'customFieldValue' => 'Mr' ), 1 => array( 'customFieldID' => '13119', 'customFieldValue' => 'Dr.' ), 2 => array( 'customFieldID' => '13120', 'customFieldValue' => 'Joe' ), 3 => array( 'customFieldID' => '13121', 'customFieldValue' => 'Smith' ), 4 => array( 'customFieldID' => '13122', 'customFieldValue' => '123456789' ), ) ); $response=$client->apiAddSubscriber(array('subscriberList'=>$subscriber));
subscriberIDList
$subscriber[0] = array( 'listID' => '123456789', 'subscriberID' => '987654321', ) );
suppressionList
$subscriber[0] = array( 'subscriberEmail' => 'joe.smith@example.com', ) );
subscriberIDListShort
$subscriber[0] = array( 'listID' => '123456789' ) );
Basics
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
Paceholder | Input |
---|---|
$client | http://api.sendcockpit.com/server.php?wsdl |
$apikey | Enter the generated API key |
$userid | Enter your User ID |
$version | The valid version is currently 1.0 |
$mode | Enter “live” to write to data. To test the API, you can leave this parameter blank or give any value (e.g. test). Then, data will only be read. |
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'];
Subscribers
ApiGetSubscriberSubscriptions
ApiGetSubscriberSubscriptions
Use this function to retrieve the subscription status of a certain subscriber.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
subscriberID | Integer | 123456789 |
Response
stdClass Object ( [subscriptionsResponse] => Array ( [0] => stdClass Object ( [listID] => 123456789 [subscriberTimestampSubscribe] => 1395692130 [subscriberTimestampUnsubscribe] => 1413447945 ) [...] ) )
Error Response
Code | Interpretation |
---|---|
404 | no subscriber found |
PHP5 Example
try { $request = array( 'subscriberID' => 123456789 ); $response = $client->apiGetSubscriberSubscriptions($request); }
Get Subscriber By Email
Getting a subscriber by email (apiGetSubscriberByEmail)
With this option, you retrieve the id and several other information of a certain subscriber by email. This function takes the email as a parameter.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
String | user@domain.com |
Response
stdClass Object ( [subsriberResponse] => stdClass Object ( [subscriberID] => 1234567 [customFields] => Array ( [0] => stdClass Object ( [customFieldID] => 1 [customFieldValue] => Mr ) [1] => stdClass Object ( [customFieldID] => 2 [customFieldValue] => John ) [2] => stdClass Object ( [customFieldID] => 3 [customFieldValue] => Yes ) [3] => stdClass Object ( [customFieldID] => 4 [customFieldValue] => 31 ) ) [subsriberHistory] => Array ( [0] => stdClass Object ( [newsletterID] => 1234 [newsletterName] => Newsletter #1 ) [1] => stdClass Object ( [newsletterID] => 1235 [newsletterName] => Newsletter #2 ) ) ) )
Error Response
Code | Interpretation |
---|---|
404 | No valid email given. |
204 | No subscriber found. |
PHP5 Example
try{ $request = array( 'email'=> 'user@domain.com' ); $response=$client->apiGetSubscriberByEmail($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Get Subscriber Unsubscribes
Getting all unsubscribed subscribers of a list (apiGetSubscriberUnsubscribes)
With this option, you retrieve all unsubscribed subscribers of a list. This function takes a list ID as a parameter. This function only provides the e-mail address.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
listID | Integer | 123456789 | apiGetList() delivers all possible List IDs. | |
start | Integer | 0 | ||
count | Integer | 100 | limited to 100 |
Response
[subsriberResponse] => Array ( [0] => stdClass Object ( [subscriberID] => 123456789 [subscriberEmail] => joe.smith@example.com [subscriberTimestampSubscribe] => 1395692130 [subscriberTimestampUnsubscribe] => 1413447945 ) [...] )
Error Response
Name | Type | Example | Required | Comment |
---|---|---|---|---|
listID | Integer | 123456789 | apiGetList() delivers all possible List IDs. | |
start | Integer | 0 | ||
count | Integer | 100 | limited to 100 |
PHP5 Example
try{ $request = array( 'start'=> 0, 'count'=> 100, 'listID'=> 123456, ); $response=$client->apiGetSubscriberUnsubscribes($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Get Subscriber Details
Getting all subscribers of a list including all custom fields (apiGetSubscriberDetails)
With this option, you retrieve all subscribers to a list. In contrast to apiGetSubscriber, the subscribers are returned together with personalization fields. The amount of data is larger, and wait time is therefore longer.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
listID | Integer | 123456789 | apiGetList() delivers all possible List IDs. | |
start | Integer | 0 | ||
count | Integer | 100 | limited to 100 |
Response
[0] => stdClass Object ( [subscriberID] => 1200863 [subscriberEmail] => max.mustermann@test.de [customFields] => Array ( [0] => stdClass Object ( [customFieldID] => 123456 [customFieldValue] => Max ) [1] => stdClass Object ( [customFieldID] => 123457 [customFieldValue] => Mustermann ) [2] => stdClass Object ( [customFieldID] => 123458 [customFieldValue] => Herr ) [3] => stdClass Object ( [customFieldID] => 123459 [customFieldValue] => Dr. ) ) [subsriberHistory] => Array ( [0] => stdClass Object ( [newsletterID] => 91 [newsletterName] => Newsletter1 [sendAt] => 2015-06-30 10:56:10 ) [1] => Array ( [newsletterID] => 92 [newsletterName] => Newsletter2 [sendAt] => 2015-10-30 10:56:27 ) [2] => Array ( [newsletterID] => 93 [newsletterName] => Newsletter3 [sendAt] => 2016-01-30 11:02:36 ) [3] => Array ( [newsletterID] => 94 [newsletterName] => Newsletter4 [sendAt] => 2016-04-03 11:03:32 ) ) ) [...]
Error Response
Code | Interpretation |
---|---|
204 | No subscribers were found in this list. Please check if a valid List ID was passed. |
404 | No valid List ID was passed. |
PHP5 Example
try{ $request = array( 'start'=> 0, 'count'=> 100, 'listID'=> 123456, ); $response=$client->apiGetSubscriberDetails($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Get Subscriber
Getting all subscribers of a list (apiGetSubscriber)
With this option, you retrieve all subscribers to a list. This function takes a list ID as a parameter. This function only provides the e-mail address and therefore works faster. If you would also like to query the personalization fields, please use apiGetSubscriberDetails.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
listID | Integer | 123456789 | apiGetList() delivers all possible List IDs. | |
start | Integer | 0 | ||
count | Integer | 100 | limited to 100 |
Response
[subsriberResponse] => Array ( [0] => stdClass Object ( [subscriberID] => 123456789 [subscriberEmail] => joe.smith@example.com [subscriberTimestampSubscribe] => 1395692130 [subscriberTimestampUnsubscribe] => 1413447945 ) [...] )
Error Response
Code | Interpretation |
---|---|
404 | No valid List ID was passed. |
PHP5 Example
try{ $request = array( 'start'=> 0, 'count'=> 100, 'listID'=> 123456, ); $response=$client->apiGetSubscriber($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Delete List
Delete a list (apiDeleteList)
Use this function to delete an existing subscriber list. The subscribers contained in the list are not deleted. They remain in the account and may no longer be associated with a list.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
listID | Integer | 123456789 | apiGetList() delivers all possible List IDs. |
Error Response
Code | Interpretation |
---|---|
404 | No List ID was passed. |
PHP5 Example
try{ $request = array( 'listID'=> 123456789, ); $response=$client->apiDeleteList($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Add List
Add a new list (apiAddList)
Use this function to set a new subscriber list.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
listName | String | New List | ||
listDescription | String | List Description |
Error Response
Code | Interpretation |
---|---|
404 | No list name was passed. |
PHP5 Example
try{ $request = array( 'listName'=> 'Neue List', 'listDescription'=> 'List Description', ); $response=$client->apiAddList($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Get List Details
Getting details of a list (apiGetListDetails)
This function provides you with more information about a single list. The name, the description, and the number of logins and logouts are specified.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
listID | Integer | 123456789 | apiGetList() delivers all possible List IDs. |
Response
stdClass Object ( [listResponse] => stdClass Object ( [listID] => 123456789 [listName] => Test List [listDescription] => Test Description [listSubscriber] => 5000 [listUnsubscriber] => 1000 ) [status] => 200 )
Error Response
Code | Interpretation |
---|---|
404 | No valid List IDs were passed. |
PHP5 Example
try{ $request = array( 'listID'=> 123456789, ); $response=$client->apiGetListDetails($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Get List
Getting all lists (apiGetList)
This function delivers all lists with List IDs.
Response
[listResponse] => Array ( [0] => stdClass Object ( [listID] => 123456 [listName] => Usergroup #1 ) [...] )
Error Response
Code | Interpretation |
---|---|
404 | No subscriber lists were created for this account. |
PHP5 Example
try{ $response=$client->apiGetList(); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Delete Subscriber Field
Delete a custom field (apiDeleteSubscriberField)
Using this function, you can delete a personalization field.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
customFieldID | Integer | 123456789 | apiGetSubscriberFieldsprovides all specified fields. |
Error Response
Code | Interpretation |
---|---|
404 | No valid CustomFieldID was passed. |
PHP5 Example
try{ $customField = array('customFieldID' => 123456789); $response=$client->apiDeleteSubscriberField($customField); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Add Subscriber Field
Add a custom field (apiAddSubscriberField)
Using this function, you can create a new personalization field.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
customFieldName | String | Surname | 1 Text, 2 Number, 3 Text with linebreak, 4 Boolean | |
customFieldType | Integer | 1 | 1 Text, 2 Number, 3 Text with linebreak, 4 Boolean |
Error Response
Code | Interpretation |
---|---|
404 | No valid custom names or custom types were passed. |
PHP5 Example
try{ $customField = array('customFieldName' => 'Surname', 'customFieldType' => 1); $response=$client->apiAddSubscriberField($customField); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Get Subscriber Fields
Getting a subscribers custom fields (apiGetSubscriberFields)
With this option, you retrieve the custom fields of the subscriber.
Response
[responseSubsriberCustomFields] => Array ( [0] => stdClass Object ( [customFieldID] => 12345 [customFieldName] => Salutation [customFieldDesc] => [customFieldType] => 1 ) [1] => stdClass Object ( [customFieldID] => 12346 [customFieldName] => Title [customFieldDesc] => [customFieldType] => 1 ) [2] => stdClass Object ( [customFieldID] => 12347 [customFieldName] => Name [customFieldDesc] => [customFieldType] => 1 ) [3] => stdClass Object ( [customFieldID] => 12348 [customFieldName] => Surname [customFieldDesc] => [customFieldType] => 1 ) [4] => stdClass Object ( [customFieldID] => 12349 [customFieldName] => Account number [customFieldDesc] => [customFieldType] => 2 ) )
Error Response
Code | Interpretation |
---|---|
null | No custom fields found for this customer. |
PHP5 Example
try{ $response=$client->apiGetSubscriberFields() } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Unsubscribe From All
Unsubscribe subscriber from all lists (apiUnsubscribeSubscriberFromAll)
Use this function to remove subscribers from all lists.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
subscriberIDList | subscriberIDList (50) | subscriberIDList | A maximum of 50 subscribers can be deleted per call |
Error Response
Code | Interpretation |
---|---|
204 | No subscribers were passed. |
404 | No valid list IDs or subscriber IDs were passed. |
PHP5 Example
$unsubscriber[0] = array( 'listID' => '123456789', 'subscriberID' => '987654321' ); $response=$client->apiUnsubscribeSubscriberFromAll(array('subscriberIDList'=>$unsubscriber));
Unsubscribe From List
Unsubscribe subscriber from list (apiUnsubscribeSubscriberFromList)
Use this function to remove subscribers from individual lists.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
subscriberIDList | subscriberIDList (50) | subscriberIDList | A maximum of 50 subscribers can be deleted per call. |
Error Response
Code | Interpretation |
---|---|
204 | No subscribers were passed. |
404 | No valid list IDs or subscriber IDs were passed. |
PHP5 Example
$unsubscriber[0] = array( 'listID' => '123456789', 'subscriberID' => '987654321' ); $response=$client->apiUnsubscribeSubscriberFromList(array('subscriberIDList'=>$unsubscriber));
Delete Subscriber
Delete subscriber (apiDeleteSubscriber)
Use this function to delete a subscriber. It is possible to delete multiple subscribers per call.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
subscriberIDListShort | subscriberIDListShort (50) | subscriberIDListShort | A maximum of 50 subscribers can be deleted per call |
Error Response
Code | Interpretation |
---|---|
204 | No subscribers were passed. |
PHP5 Example
$subscriberDelete[0] = array( 'subscriberID' => '123456789' ); $response=$client->apiDeleteSubscriber(array('subscriberIDListShort'=>$subscriberDelete));
Add Subscriber Doi
Adding a subscriber using Double-Opt-In (apiAddSubscriberDoi)
Use this function to add subscribers to a subscriber list. The subscriber must have a valid e-mail. Personalization fields can be passed (max 25), and for this purpose, the customFieldID and all relevant content must be transmitted. If an incorrect customFieldID is passed, personalization fields are not applied.
If a subscriber to be created is already present in the system, their personalization fields will be overwritten with the new values.
This function uses the double opt-in method. The given subscriber will receive an e-mail containing an activation link. Only after clicking this link is the subscriber added to the subscriber list. If this is not desired, apiAddSubscriber should be used.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
subscriberList | subscriberList (50) | subscriberList | A maximum of 50 subscribers can be passed per call |
Error Response
Code | Interpretation |
---|---|
204 | No subscribers were passed. |
404 | No valid list IDs were passed. |
416 | An invalid e-mail address was passed. |
PHP5 Example
try{ $subscriber[0] = array( 'listID' => '123456789', 'email' => 'mustermann@test.de', 'customFields' => array( 0 => array( 'customFieldID' => '12345', 'customFieldValue' => 'Herr' ), 1 => array( 'customFieldID' => '12346', 'customFieldValue' => 'Dr.' ), 2 => array( 'customFieldID' => '123457', 'customFieldValue' => 'Max' ), 3 => array( 'customFieldID' => '123458', 'customFieldValue' => 'Mustermann' ), ) ); $response=$client->apiAddSubscriberDoi(array('subscriberList'=>$subscriber)); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Add Subscriber
Adding a subscriber (apiAddSubscriber)
Use this function to add subscribers into a subscriber list. The subscriber must have a valid e-mail. Personalization fields may be passed (max 25). For this, the customFieldID and all relevant content must be passed. If an incorrect customFieldID is passed, no personalization fields are applied.
If a subscriber to be created is already present in the system, their personalization fields will be overwritten with the new values.
If the double opt-in method is desired for logging in, apiAddSubscriberDoi must be used.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
subscriberList | subscriberList (50) | subscriberList | A maximum of 50 subscribers can be passed per call. |
Error Response
Code | Interpretation |
---|---|
204 | No subscribers were passed. |
404 | No valid list IDs were passed. |
416 | An invalid e-mail address was passed. |
PHP5 Beispiel
try{ $subscriber[0] = array( 'listID' => '123456789', 'email' => 'mustermann@test.de', 'customFields' => array( 0 => array( 'customFieldID' => '12345', 'customFieldValue' => 'Herr' ), 1 => array( 'customFieldID' => '12346', 'customFieldValue' => 'Dr.' ), 2 => array( 'customFieldID' => '123457', 'customFieldValue' => 'Max' ), 3 => array( 'customFieldID' => '123458', 'customFieldValue' => 'Mustermann' ), ) ); $response=$client->apiAddSubscriber(array('subscriberList'=>$subscriber)); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Get Subscriber History
Getting a subscriber’s history (apiGetSubscriberHistory)
With this function, you can call up the history of a subscriber. It displays all the mailings that have been received by the subscriber.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
subscriberID | Integer | 123456789 | apiGetSubscriber provides all possible subscriber IDs in a list |
Response
[subsriberHistoryResponse] => Array ( [0] => stdClass Object ( [newsletterID] => 1234 [newsletterName] => Newsletter #1 ) [1] => stdClass Object ( [newsletterID] => 1235 [newsletterName] => Newsletter #2 ) [...] )
Error Response
Code | Interpretation |
---|---|
204 | No history was found for the subscriber. |
404 | No valid ID list was passed. |
PHP5 example
try{ $request = array( 'subscriberID'=> 123456789 ); $response=$client->apiGetSubscriberHistory($request); } catch (SoapFault $exception) { echo ($exception->getMessage()); }
Campaigns
Get Newsletter Receivers
apiGetNewsletterReceivers
Use this function to retrieve all receivers of a certain campaign.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
newsletterID | Integer | 5 | ||
start | Integer | 5 | ||
count | Integer | 100 | Max value for this one is 10 000 |
Response
stdClass Object ( [newsletterReceiversResponse] => Array ( [0] => stdClass Object ( [subscriberID] => 12 [subscriberEmail] => myemail1@example.com [subscriberBounceStatus] => false ) [1] => stdClass Object ( [subscriberID] => 13 [subscriberEmail] => myemail2@example.com [subscriberBounceStatus] => hb ) [2] => stdClass Object ( [subscriberID] => 14 [subscriberEmail] => myemail3@example.com [subscriberBounceStatus] => sb ) [...] ) )
Error Response
Code | Interpretation |
---|---|
404 | No receivers are found |
PHP5 Example
try { $request = array( 'newsletterID' => 100 'start'=>0, 'count'=>10 ); $response = $client->apiGetNewsletterReceivers($request); }
Get Sent Newsletters
apiGetSentNewsletters
Use this function to retrieve all sent campaigns. Does not return any test campaigns.
Request
Name | Type | Example | Required | Comment |
---|---|---|---|---|
start | Integer | 5 | ||
count | Integer | 100 | Max value for this one is 100 |
Response
stdClass Object ( [sentNewslettersResponse] => Array ( [0] => stdClass Object ( [newsletterID] => 126 [newsletterName] => My awesome newsletter [sentAt] => 2015-09-01 10:28:35 ) [...] ) )
Error Response
Code | Interpretation |
---|---|
404 | No campaigns found |
PHP5 Example
try { $request = array( 'start'=>0, 'count'=>10 ); $response = $client->apiGetSentNewsletters($request); }