Dokumentation der API unserer Newsletter-Software

Hier finden Sie die aktuell verfügbaren Funktionen und die zugehörige Beschreibung der angebotenen API Funktionen.

API Dokumentation

1. Definition

SOAP (ursprünglich für Simple Object Access Protocol) ist ein Netzwerkprotokoll, mit dessen Hilfe Daten zwischen Systemen ausgetauscht und Remote Procedure Calls durchgeführt werden können. SOAP stützt sich auf XML zur Repräsentation der Daten und auf Internet-Protokolle der Transport- und Anwendungsschicht (vgl. TCP/IP-Referenzmodell) zur Übertragung der Nachrichten. Die gängigste Kombination ist SOAP über HTTP und TCP. Die Abkürzung SOAP wird offiziell seit Version 1.2 nicht mehr als Akronym gebraucht, da es erstens (subjektiv) keineswegs einfach (Simple) ist und zweitens nicht nur dem Zugriff auf Objekte (Object Access) dient.

Quelle: http://de.wikipedia.org/wiki/SOAP

2. Zielgruppe

Dieses Dokument richtet sich an Softwareentwickler welche eine Anbindung dieser E-Mail Marketing Software an bestehende Legacy Systeme implementieren möchten. Um das zum Einsatz kommende WSDL-Dokument zu verstehen, in dem die verfügbaren Funktionen und Datentypen beschrieben werden, sind Kenntnisse im Bereich WSDL und XML-Schema von Vorteil.

3. Einleitung

Die Schnittstelle ermöglicht den automatisierten Zugriff auf hinterlegte Datensätze und ausgewählte Funktionen zur Automatisierung der Newsletter-Software. Auf diese Art können bestehende Systeme angebunden und wiederkehrende Vorfälle automatisiert werden. Beispielsweise können Kundendaten und Newsletter übertragen werden.

4. Web Services Description Language (WSDL)

Die zugehörige WSDL finden Sie unter http://www.newstroll.de/app/ws/2013-02/?wsdl. Es wird eine Authorisierung benötigt.

5. Methoden

Übersicht der bereitgestellten Methoden

SOAP Connect

Abonnenten anmelden/abmelden

Abonnenten Informationen

Verteiler

Mailings (Newsletter & Co)

Statistiken

5.1. SOAP Verbindung herstellen

try {
	ini_set("soap.wsdl_cache_enabled", "0");
	$client = new SOAPClient('http://www.newstroll/app/ws/2013-02/?wsdl',
		array(
		'login' => '*LOGIN*',
		'password' => '*PASSWORD*','exceptions' => 1)
		);

	$securityToken = '*IHRSECURITYTOKEN*';
}

catch (SOAPFault $f) {
	echo $f->faultstring;
}

5.2.1. Abonnenten anmelden / abmelden

notwendige Klassen

class Subscription {
	public $email = null; // E-Mail Adresse
	public $workflow = false;  // Double-Opt-In nutzen ?
	public $personalization = array(); // Personalisierungen
public $vacation_from = null; // format: d.m.Y
public $vacation_to = null; // format: d.m.Y public function Subscription($email,$personalizations = array()) { $this->email = $email; $this->personalizations = $personalizations; } } class Personalization { public $label; public $value; public function Personalization($label,$value) { $this->label = $label; $this->value = $value; } }

neue Subscription anlegen

$personalization = array(
	new Personalization('Alter','43'),
	new Personalization('Vorname','Marc')
);
$sub = new Subscription('my.email@gmail.com',$personalization); 
echo $client->addSubscription($securityToken,$sub,'*Verteiler-ID*');

$sub = new Subscription('my.email@gmail.com'); echo $client->removeSubscription($securityToken,$sub,'*Verteiler-ID*');

Der Beispielcode setzt voraus, dass Sie eine Personalisierung mit dem Label "Alter" sowie "Vorname" angelegt haben.

Rückgabewerte:

0: Fehler bei Anmeldung oder Abmeldung - bitte erneut probieren bzw. Support kontaktieren wenn dauerhaft
1: Erfolg
2: bereits vorhanden - Eintrag aktualisiert
3: Eintrag auf Blacklist
4: Eintrag auf globaler Blacklist
5: Blacklist wegen Hard-Bounce (unbekannter Benutzer)
6: keine valide E-Mail
 

Abmeldungen oder Bounces auslesen

$users = $client->getSubscriptionsByStatus($securityToken,'**Verteiler-ID**', 31, 5);
foreach ($users as $user) {
echo 'email: ' . $user->email . ' <br />';
}

Der Funktion getSubscriptionsByStatus() können Sie dabei die Anzahl der Tage übergeben sowie einen Filter, welche Abonnements Sie auslesen möchten. Bounces werden mit Status 4 ausgelesen und Abmeldungen (wie in obigem Beispiel) mit Status 5.

Eine Abfrage für die Abmeldungen der letzten 7 Tage sieht dann so aus:

$users = $client->getSubscriptionsByStatus($securityToken,'**Verteiler-ID**', 7, 5);

5.2.2 Abonnenten Informationen

Informationen über Abonnenten abrufen

 $user = $client->getUserDetails($securityToken,'my.email@gmail.com'); 

Über diese Funktion können Sie alle gespeicherten Informationen (Double-Opt-In Daten, Bounce Status, Urlaubseintragung usw.) über die gewünschte E-Mail Adresse abrufen. 

5.3. Verteiler

Verteiler auslesen

     $groups = $client->getGroups($securityToken);

    // Anzeige aller Gruppen IDs und Titel
    foreach ($groups as $g) {
        echo 'ID: ' . $g->id . ' Titel: ' . $g->title . '<br />';
    }


5.4. Mailings

Newsletter importieren

Wir bieten Ihnen die Möglichkeit, aus Ihrem bestehenden Content Management System, Forum oder zum Beispiel aus Ihrem Board heraus automatisch erstellte Newsletter in unser System zu importieren und anschließend versenden zu lassen. Im Folgenden werden die einzelnen XML Elemente erklärt.

Erklärung der XML-Elemente

XML-ElementOptionErklärung
group   Verteiler-ID, an welcher Newsletter versandt werden soll (nur bei Status TOSEND)
format TEXT Textformat
  HTML HTML-Format
senddate TT.MM.JJJJ Versanddatum, z.B.
sendtime HH:MM:SS Versandzeitpunkt, z.B.
status CREATED Status im Workflow ist "Newsletter wird bearbeitet"
Der NL wird nicht versendet. Sie müssen diesen noch fertig bearbeiten und manuell einen Versandauftrag anlegen.
  APPROVED Status im Workflow ist "Newsletter ist erstellt"
Der NL wird nicht versendet. Sie müssen noch manuell einen Versandauftrag anlegen.
  TOSEND Status im Workflow ist: "Versandauftrag angelegt"
Nur in diesem Status wird der NL automatisch versendet.
mailpriority LOW Priorität der versendeten E-Mail ist niedrig.
  NORMAL Priorität der versendeten E-Mail ist normal.
  HIGH Priorität der versendeten E-Mail ist hoch.
title   Betreff des Newsletters
campaign_name   Name der Kampagne zu der dieser Newsletter zugeordnet werden soll.
content   Inhalt des Newsletters
attachments   Anhänge (z.B. eingebettetes Bild oder eine PDF Datei)
  location URL zum Anhang 1
  location URL zum Anhang 2

Komplettes XML Beispiel eines Newsletters (Quelltext)

<?xml version="1.0" encoding="UTF-8"?>
<order>
    <group>3422</group>
    <format>TEXT</format>
    <senddate>14.02.2013</senddate>
    <sendtime>13:00:00</sendtime>
    <status>TOSEND</status>
    <mailpriority>NORMAL</mailpriority>
    <title>Aktueller Newsletter #34</title>
    <campaign_name>Standard-Kampagne</campaign_name>
    <content><![CDATA[BeispielFeed newstroll.de
http://www.newstroll.de

+---------------------------------------------------------------------+
Antworten, Kommentare oder Kritik veroeffentlichen Sie bitte
im Forum unter http://www.newstroll.de
+---------------------------------------------------------------------+

Hallo liebe Internetterinnen und Internetter,
sehr geehrte Damen und Herren,

soeben wurde ..........

+---------------------------------------------------------------------+
IMPRESSUM
+---------------------------------------------------------------------+

Copyright 1999 by NEWSTROLL
Redaktion NEWSTROLL

Chefredakteur: N.N. (V.i.S.d.P.)
eMail: N.N.@newstroll.de - Web: http://www.newstroll.de

Copyright-Hinweis: Artikel aus diesem Feed düfen nur unter der
Angabe [Quelle: www.newstroll.de] weiterverwendet werden!

Newsfeed powered by NEWSTROLL - http://www.newstroll.de/
newstroll.de - Newsletterhosting, -Marketing und -Service]]></content>
<attachments>
    <location>http://www.newstroll.de/Funktionen.pdf</location>
    <location>http://www.newstroll.de/Preise.pdf</location>
</attachments>
</order>

Um den Newsletter nun zu importieren, legen Sie die XML Datei auf Ihrem Server ab und nutzen Sie den nachfolgenden PHP Code. Die Variable $xml_uri ist nun die URL zu Ihrer XML-Datei auf Ihrem Server. Bitte stellen Sie sicher, dass diese von außen lesbar ist.

Methode

     $xml_uri = 'http://ihredomain.de/newsletter/newsletter.xml';
    echo $client->importNewsletter($securityToken,$xml_uri);

Probleme und Fehlermeldungen

Folgende Fehler-Codes gibt unsere SOAP Schnittstelle zurück.

 0 - Speicherung nicht möglich. Systemfehler
1 - Erfolgreich importiert
2 - XML Datei nicht gefunden
3 - Verteiler nicht angegeben oder gefunden
5 - Keine Versandzeit angegeben
6 - Kein Betreff angegeben
7 - Kein Inhalt angegeben
9 - maximale Größe der Anhänge erreicht
10 - Fehler beim Abrufen der Anhänge
12 - Keine Berechtigung

5.5. Statistiken

Statistikdaten werden über die SOAP Schnittstelle nicht zur Verfügung gestellt. Aber die erstellten Statistiken werden im Backend als Tabellen oder als Grafiken bereit gestellt.

Beide Darstellungen können manuell exportiert werden, um diese z.B. in Präsentationen nutzen zu können.