So verwenden Sie unsere JSON Schnittstelle

Die mailworx Schnittstelle ist mittels eines JSON Webservice realisiert, der unter der URL https://mailworx.marketingsuite.info/Services/JSON/ServiceAgent.svc erreichbar ist.

Die Schnittstellendefinition finden Sie unter https://mailworx.marketingsuite.info/Services/JSON/ServiceAgent.svc?WSDL.

Aufruf-Konzept des JSON Webservice

Die mailworx JSON Webservice Schnittstelle erwartet als Übergabeparameter bei jedem Aufruf ein JSON Objekt und retourniert als Ergebnis ebenfalls ein JSON Objekt.

Das Objekt, das beim Aufruf übergeben wird, muss alle Informationen enthalten, die zur Ausführung der entsprechenden Methode notwendig sind. Bei jedem Aufruf müssen mindestens die Login Daten und die Sprache übergeben werden. Alle weiteren Eigenschaften sind abhängig von der aufgerufenen Methode.

Das Objekt, das als Ergebnis retourniert wird, enthält entsprechende methodenspezifische Daten.

Die mailworx JSON Webservice Schnittstelle verwaltet bei der Verwendung keinen Status. Es ist daher erforderlich, dass die Login Daten bei jedem Methodenaufruf mitgegeben werden. Die Login Daten für mailworx werden unverschlüsselt angegeben. Aus diesem Grund empfiehlt es sich, die JSON Webservice Schnittstelle ausschließlich über HTTPS aufzurufen.

Die Login Daten bestehen aus vier Eigenschaften: Account, Username, Password, Source. Die Eigenschaft Source ist der Name der Anwendung, welche die mailworx Schnittstelle aufruft. Die Anwendung bzw. der hier angeführte Name muss von eworx Network & Internet GmbH zur Verwendung freigegeben werden. Weiters wird von eworx Network & Internet GmbH festgelegt, welche Methoden der mailworx Schnittstelle für diese Anwendung zur Verfügung stehen.

Da mailworx verschiedensprachige Newsletter verwalten kann, erfordert jeder Aufruf auch eine Eigenschaft „Language“, die mit dem entsprechenden Sprachkürzel zu verwenden ist (z.B. de, EN, …).

Durch diese Ausführung ergibt sich, dass jedes zu übergebende JSON Objekt mindestens zwei Eigenschaften besitzt: „Language“ undSecurityContext (in dem Account, Username, Password, Source definiert sind).

Folgendes Beispiel soll die Verwendung der JSON Webservice Schnittstelle mit Hilfe der Methode ImportSubscribers veranschaulichen:

<?php
// the path to the webservice
$webserviceUrl = "http://mailworx.marketingsuite.info/Services/JSON/ServiceAgent.svc";

// needed for authentication
$securityContext = array(
"Account" => "account",
"Username" => "username",
"Password" => "******",
"Source" => "api name"
);


// stores the list of subscriber
$subscribers = array();

// fill $subscribers with $subscriber
array_push($subscribers, array(
"OptIn" => false,
"Fields" => array(
array(
"__type" => "TextField:#Eworx.Mailworx.ServiceInterfaces",
"InternalName" => "email",
"UntypedValue" => "email@provider.at"
)
)
));

// build the request
$data = array(
"request" => array(
"Language" => "DE", // language of the import
"SecurityContext" => $securityContext, // security context
"DuplicateCriteria" => "email", // fieldname of the duplicate criteria for the import
"Subscribers" => $subscribers // the subscriber data as list
)
);

// convert array to json
$json = json_encode($data);

// call the webservice url with the wanted method
$ch = curl_init($webserviceUrl . "/ImportSubscribers");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Content-Type: application/json',
'Content-Length: ' . strlen($json))
);

// FINISH
$result =curl_exec($ch);
?>

Um das System zu entlasten und die höchstmögliche Zuverlässigkeit zu gewährleisten, ist das Request Limit auf 300 Aufrufe pro Minute beschränkt.

Absichern der JSON Webservice Schnittstelle

Der JSON Webservice kann per JSON over HTTP oder JSON over HTTPS verwendet werden. Durch die Verwendung von HTTPS wird die Kommunikation zwischen Clients und Server verschlüsselt und die Datenübertragung via JSON Webservice abgesichert.

Zahlreiche Konzepte wurden zum Schutz Ihrer Daten sowie für die Sicherheit und Stabilität des mailworx Systems ausgearbeitet und umgesetzt.

Die mailworx Plattform wird in einem zentralen Rechenzentrum in Linz betrieben und ist direkt an den hochverfügbaren Internetbackbone angebunden. Modernste Firewall Technologien und konstantes Monitoring garantieren bestmöglichen Schutz.