Allgemeines

Die API arbeitet mit dem Netzwerkprotokoll SOAP (Simple Object Access Protokoll). Für SOAP finden sich Bibliotheken in vielen modernen Programmiersprache wie PHP, Python, Java und C++. SOAP bietet somit eine gute Grundlage für eine einfache und sprachübergreifende Kommunikation. Grundlage für SOAP ist die WSDL-Datei, in der alle Funktionen und Parameter der API beschrieben werden. Die WSDL-Datei wird im XML Format zur Verfügung gestellt und kann von vielen Editoren (z.B. Aptana) gelesen werden.

API Key

Einleitung

Um mit der API kommunizieren zu können benötigen Sie einen API Key und Ihre User ID. Mittels dieser Daten werden Sie eindeutig für die Arbeit mit der API identifiziert und haben Zugriff auf Ihren Account.

API Key erstellen

Sie benötigen für jeden Account einen eigenen API Key und die dazugehörige User ID. Um Ihren API Key zu erstellen und Ihre User ID anzuzeigen, loggen Sie sich bitte in Ihren Account ein und klicken Sie ganz unten im Footer auf API. Klicken Sie anschließend auf den Button API Key generieren.

Client einrichten (am Beispiel von PHP5)

Viele moderne Programmiersprachen bieten bereits eine fertige Bibliothek mittels der Sie schnell und einfach SOAP Funktionen nutzen können.

<!--?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 Konstanten

Konfigurieren Sie Ihren Client wie folgt

Authentifizierung

Die Authentifizierung über die API erfolgt über den SOAP Header. Der Name des Header lautet validate. Dem Header wird ein Objekt übergeben das den API Key, die User ID, die API Version und den API Modus als Eigenschaft beinhaltet. Scheitert die Authentifizierung wird eine Fehlermeldung zurückgegeben. Die Authentifizierung muss bei jedem Funktionsaufruf durchgeführt werden.

PHP5 Beispiel: 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);

Eingabewerte

Die meisten Funktionen erwarten Eingabeparameter. Alle Parameter (auch einzelne) werden als Liste an die Funktion übergeben. Wenn z.B. alle Subscriber einer Empfängerliste abgefragt werden sollen sieht der Funktionsparameter folgendermaßen aus.

PHP5 Beispiel

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

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

Den Datentyp eines Paramters können Sie der Funktionsbeschreibung entnehmen. Sie können der Beschreibung auch entnehmen, wie groß die Daten jeweils sein dürfen und ob es sich um Pflichtangaben handelt. Die Struktur von komplexen Datentypen wird ebenfalls in der jeweiligen Parameterliste beschrieben.

Parameterlisten haben als Ein- und Rückgabewerte immer eine maximale Größe. Sollten zu übertragene Listen größer als das in der Beschreibung angegebene Maximum sein, müssen sie mittels einer Schleife abgefragt werden. Dazu stehen den jeweiligen Funktionen die Parameter start und countzur Verfügung. Der Parameter start definiert dabei an welcher Stelle die Abfrage aus der Datenbank beginnen soll und count gibt an wie viele Datensätze ab start übergeben werden sollen.

PHP5 Beispiel: Rückgabe von 100 Empfängern ab Position 500

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

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

Rückgabewerte

Die Schnittstelle liefert Rückgabewerte in einem stdClass Object. Wenn Sie mit diesem Format nicht vertraut sind, können Sie das Objekt – wie z.B. in PHP – in ein assoziatives Array umwandeln.

Folgendes Beispiel zeigt ein stdClass Object, wie sie auf ein einzelnes Element zugreifen können, wie sie das Objekt umwandeln und als Array behandeln können.

PHP5 Beispiel: Zugriff auf ein einzelnes Element > Umwandlung als Array

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

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

//Ausgabe als stdClass Object

echo $subsriberResponse[0]->subscriberID;

//Umwandeln und Ausgabe als Array

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