API Documentation

Introduction

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).

A maximum of 10,000 API requests can be sent every 24 hours.

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.

01-api-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

PaceholderInput
$clienthttp://api.sendcockpit.com/server.php?wsdl
$apikeyEnter the generated API key
$useridEnter your User ID
$versionThe valid version is currently 1.0
$modeEnter “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'];

Back To Top

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'
 )
);

Back To Top

Subscribers

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

NameTypeExampleRequiredComment
subscriberIDInteger123456789apiGetSubscriber 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

CodeInterpretation
204 No history was found for the subscriber.
404No valid ID list was passed.

PHP5 example

try{
 $request = array(
 'subscriberID'=> 123456789
 );

 $response=$client->apiGetSubscriberHistory($request);
}
catch (SoapFault $exception) {
 echo ($exception->getMessage());
}

Back To Top

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

NameTypeExampleRequiredComment
subscriberListsubscriberList (50) subscriberListA maximum of 50 subscribers can be passed per call.

Error Response

CodeInterpretation
204No subscribers were passed.
404No valid list IDs were passed.
416An 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());
}

Back To Top

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

NameTypeExampleRequiredComment
subscriberListsubscriberList (50) subscriberListA maximum of 50 subscribers can be passed per call

Error Response

CodeInterpretation
204No subscribers were passed.
404No valid list IDs were passed.
416An 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());
}

Back To Top

Delete Subscriber

Delete subscriber (apiDeleteSubscriber)

Use this function to delete a subscriber. It is possible to delete multiple subscribers per call.

Request

NameTypeExampleRequiredComment
subscriberIDListShortsubscriberIDListShort (50) subscriberIDListShortA maximum of 50 subscribers can be deleted per call

Error Response

CodeInterpretation
204No subscribers were passed.

PHP5 Example

$subscriberDelete[0] = array(
    'subscriberID' => '123456789'
);

$response=$client->apiDeleteSubscriber(array('subscriberIDListShort'=>$subscriberDelete));

Back To Top

Unsubscribe From List

Unsubscribe subscriber from list (apiUnsubscribeSubscriberFromList)

Use this function to remove subscribers from individual lists.

Request

NameTypeExampleRequiredComment
subscriberIDListsubscriberIDList (50) subscriberIDListA maximum of 50 subscribers can be deleted per call.

Error Response

CodeInterpretation
204No subscribers were passed.
404No valid list IDs or subscriber IDs were passed.

PHP5 Example

$unsubscriber[0] = array(
    'listID' => '123456789',
    'subscriberID' => '987654321'
);

$response=$client->apiUnsubscribeSubscriberFromList(array('subscriberIDList'=>$unsubscriber));

Back To Top

Unsubscribe From All

Unsubscribe subscriber from all lists (apiUnsubscribeSubscriberFromAll)

Use this function to remove subscribers from all lists.

Request

NameTypeExampleRequiredComment
subscriberIDListsubscriberIDList (50) subscriberIDListA maximum of 50 subscribers can be deleted per call

Error Response

CodeInterpretation
204No subscribers were passed.
404No valid list IDs or subscriber IDs were passed.

PHP5 Example

$unsubscriber[0] = array(
    'listID' => '123456789',
    'subscriberID' => '987654321'
);

$response=$client->apiUnsubscribeSubscriberFromAll(array('subscriberIDList'=>$unsubscriber));

Back To Top

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

CodeInterpretation
204No custom fields found for this customer.

PHP5 Example

try{
    $response=$client->apiGetSubscriberFields()
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}

Back To Top

Add Subscriber Field

Add a custom field (apiAddSubscriberField)

Using this function, you can create a new personalization field.

Request

NameTypeExampleRequiredComment
customFieldNameStringSurname1 Text, 2 Number, 3 Text with linebreak, 4 Boolean
customFieldTypeInteger11 Text, 2 Number, 3 Text with linebreak, 4 Boolean

Error Response

CodeInterpretation
404No 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());
}

Back To Top

Delete Subscriber Field

Delete a custom field (apiDeleteSubscriberField)

Using this function, you can delete a personalization field.

Request

NameTypeExampleRequiredComment
customFieldIDInteger123456789apiGetSubscriberFieldsprovides all specified fields.

Error Response

CodeInterpretation
404No valid CustomFieldID was passed.

PHP5 Example

try{
    $customField = array('customFieldID' => 123456789);
    $response=$client->apiDeleteSubscriberField($customField);
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}

Back To Top

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

NameTypeExampleRequiredComment
emailStringuser@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

CodeInterpretation
404No valid email given.
204No subscriber found.

PHP5 Example

try{
    $request = array(
        'email'=>       'user@domain.com'
    );
    $response=$client->apiGetSubscriberByEmail($request);
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}

Back To Top

ApiGetSubscriberSubscriptions

ApiGetSubscriberSubscriptions

Use this function to retrieve the subscription status of a certain subscriber.

Request

NameTypeExampleRequiredComment
subscriberIDInteger123456789

Response

stdClass Object
(
[subscriptionsResponse] => Array
      (
          [0] => stdClass Object
              (
                  [listID] => 123456789
                  [subscriberTimestampSubscribe] => 1395692130
                  [subscriberTimestampUnsubscribe] => 1413447945
              )
         [...]
      )
)

Error Response

CodeInterpretation
404no subscriber found

PHP5 Example

try {
   $request = array(
         'subscriberID' => 123456789
   );
   $response = $client->apiGetSubscriberSubscriptions($request);
}

Back To Top

Lists

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

CodeInterpretation
404No subscriber lists were created for this account.

PHP5 Example

try{
    $response=$client->apiGetList();
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}

Back To Top

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

NameTypeExampleRequiredComment
listIDInteger123456789apiGetList() 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

CodeInterpretation
404No valid List IDs were passed.

PHP5 Example

try{
    $request = array(
 
        'listID'=> 123456789,
 
);
    $response=$client->apiGetListDetails($request);
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}

Back To Top

Add List

Add a new list (apiAddList)

Use this function to set a new subscriber list.

Request

NameTypeExampleRequiredComment
listNameStringNew List
listDescriptionStringList Description

Error Response

CodeInterpretation
404No 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());
}

Back To Top

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

NameTypeExampleRequiredComment
listIDInteger123456789apiGetList() delivers all possible List IDs.

Error Response

CodeInterpretation
404No List ID was passed.

PHP5 Example

try{
$request = array(
    'listID'=> 123456789,
);
 
$response=$client->apiDeleteList($request);
 
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}

Back To Top

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

NameTypeExampleRequiredComment
listIDInteger123456789apiGetList() delivers all possible List IDs.
startInteger0
countInteger100limited to 100

Response

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

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

            [subscriberTimestampSubscribe] => 1395692130

            [subscriberTimestampUnsubscribe] => 1413447945
        )
   [...]
)

Error Response

CodeInterpretation
404No 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());
}

Back To Top

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

NameTypeExampleRequiredComment
listIDInteger123456789apiGetList() delivers all possible List IDs.
startInteger0
countInteger100limited 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

CodeInterpretation
204No subscribers were found in this list. Please check if a valid List ID was passed.
404No 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());
}

Back To Top

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

NameTypeExampleRequiredComment
listIDInteger123456789apiGetList() delivers all possible List IDs.
startInteger0
countInteger100limited to 100

Response

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

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

            [subscriberTimestampSubscribe] => 1395692130

            [subscriberTimestampUnsubscribe] => 1413447945
        )
   [...]
)

Error Response

NameTypeExampleRequiredComment
listIDInteger123456789apiGetList() delivers all possible List IDs.
startInteger0
countInteger100limited to 100

PHP5 Example

try{
    $request = array(
        'start'=>       0,
        'count'=>       100,
        'listID'=> 123456,
    );
    $response=$client->apiGetSubscriberUnsubscribes($request);
}
catch (SoapFault $exception) {
    echo ($exception->getMessage());
}

Back To Top

Campaigns

Get Sent Newsletters

apiGetSentNewsletters

Use this function to retrieve all sent campaigns. Does not return any test campaigns.

Request

NameTypeExampleRequiredComment
startInteger5
countInteger100Max 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

CodeInterpretation
404No campaigns found

PHP5 Example

try {
   $request = array(
         'start'=>0,
         'count'=>10
   );
   $response = $client->apiGetSentNewsletters($request);
}

Back To Top

Get Newsletter Receivers

apiGetNewsletterReceivers

Use this function to retrieve all receivers of a certain campaign.

Request

NameTypeExampleRequiredComment
newsletterIDInteger5
startInteger5
countInteger100Max 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

CodeInterpretation
404No receivers are found

PHP5 Example

try {
   $request = array(
         'newsletterID' => 100
         'start'=>0,
         'count'=>10
   );
   $response = $client->apiGetNewsletterReceivers($request);
}

Back To Top