Diese Kapitel beschreibt eine sogenannte API für den Zugriff auf die Abonnentendatenbank. Als Alternative zu den Templates zur Anmeldung, Abmeldung oder Profiländerung bietet Ihnen BACKCLICK die Möglichkeit, Abonnententransaktionen über das Protokoll 'http' durchzuführen. Diese API ist für die Kommunikation zwischen zwei Serverprozessen gedacht und liefert demnach keine verständlichen Ausgaben, sondern nur Statuscodes.
Wenn bereits eine Anmeldeseite existiert (z. B. für Ihre Kundendatenbank, Ihr Shopsystem), können Sie aus den gewonnenen Daten eine URL (Link) generieren lassen, der die Abonnenten zusätzlich noch in die Abonnentendatenbank von BACKCLICK einträgt. Sie können die Daten dann von der Applikation direkt per http an BACKCLICK übertragen lassen. Das hat den Vorteil, dass Sie nur eine Anmeldeseite (Applikation) benötigen, um die Daten mehrfach nutzen können. Des Weiteren können so Ihre Applikationen direkt mit BACKCLICK auf Protokollebene kommunizieren.
Aufgrund der Mandantenfähigkeit von BACKCLICK muss in jedem Aufruf der HTTP-API die gewünschte Mandanten-ID übergeben werden. Sollte keine Mandanten-ID übergeben werden, wird der Aufruf dem Mandanten mit der ID=0 zugewiesen.
! ACHTUNG SICHERHEIT !
Diese Interface kann ohne spezielle Einschränkungen von allen Servern und Arbeitsstationen (IP Adressen) aufgerufen werden. Um dies einzuschränken, können Sie in Systemadministration --> Grundeinstellungen -> WebInterface die IP-Adressen angeben, von denen ein ausschließlicher Zugriff erlaubt wird. Dazu muss die Checkbox vor "HTTP Abonnenten API" aktiviert werden, um rechts in der Textarea die entsprechende/n IP Adresse/n einzutragen.
Folgende Funktionen werden von dieser API unterstützt:
- Anmeldung von neuen Abonnenten an beliebigen,
vorhandenen Verteilerlisten
- Änderung des Abonnentenprofils inklusive der Änderung
der Email-Adresse
- Zusätzliche Bestellung von Newslettern
- Abmeldung bestehender Abonnenten (komplett oder nur
bestimmte Verteilerlisten)
Allgemeines
Sämtliche Funktionen werden über das HTTP-Protokoll aufgerufen. Zu jedem Aufruf wird ein Statuscode von BACKCLICK zurückgegeben. Die URL für die Kommunikation wird wie folgt gebildet:
http://domain.kunde.de/bc/servlet/web.httpapi?..
Als Parameter werden folgende Werte anerkannt:
- NEWEMAIL
- NEWSLETTER (ID der Verteilerliste/n)
- PASSWORD
- CHANGETYPE (nur beim Profiländerungen, additive Änderung =1, absolute Änderung =0)
- SENDCONFIRM (versendet An/Abmeldebestätigung = 1, versendet keine An/Abmeldebestätigung = 0)
- XXXXXXX (sämtliche Variablen (Namen), die im Datenbankdesigner definiert sind)
- DELETE (ohne Angabe von NEWSLETTER wird der Abonnent gelöscht =1, mit Angabe von NEWSLETTER/Verteilerlisten IDs wird der Abonnent nur von den übergebenen IDs abgemeldet)
- MAKENOUPDATE (verhindert das Überschreiben bzw. Erweitern vohandener Stammdaten eines Abonnenten, falls der Abonnent schon im System vorhanden ist =1, Default = 0)
- DOI-TEMPLATE (ID des Double-Opt-In-Webinterface-Templates, welches für Neuanmeldungen verwendet werden soll. Wenn hier Template angegeben ist, wird der Abonnent nicht sofort auf neue Verteilerlisten angemeldet. Der Abonnent bekommt erst eine Bestätigungs-Mail, welche auf dem Template basiert, zugesendet.)
Pflichtparameter sind grundsätzlich EMAIL und NEWSLETTER (es sei denn, ein Abonnent soll gelöscht werden, NEWSLETTER wird dann durch DELETE=1 ersetzt). Als optionale Parameter sind alle Parameter gültig, die im Datenbankdesigner angelegt wurden.
Anmeldung von neuen Abonnenten an beliebigen vorhandenen Verteilerlisten
Beispiel:
http://domain.kunde.de/bc/servlet/web.httpapi?EMAIL=abc@def.gh&NACHNAME=Mustermann&VORNAME=Max&NEWSLETTER=1;2&MID=0
Hier kann man sehen, dass es auch möglich ist, vorhandene Datenbankfelder gleich mit auszufüllen (hier VORNAME, NACHNAME). Zuordnungen zu Verteilerlisten (NEWSLETTER) müssen bei mehreren Listen mit Semikolon getrennt werden.
Wenn der Abonnent mit einem Double-Opt-In angemeldet werden soll, kann hier der Parameter DOI-TEMPLATE mit übergeben werden. Der Wert muss der ID eines aktiven Double-Opt-In-Webinterface-Templates entsprechen, welches in Backclick hinterlegt ist. (Mehr zu Webinterface-Templates, hier: Anmeldung (Double-opt-in))
Änderung des Abonnentenprofils inkl. Änderung der Email-Adresse
Die URL sieht hier genauso aus, wie beim Anlegen eines Abonnenten. Sollte BACKCLICK feststellen, dass unter der übergebenen Email-Adresse bereits ein Abonnent verzeichnet ist, so ändert BACKCLICK dessen Profil. Hier wurde dem Abonnenten zusätzlich ein Passwort zugewiesen und die Verteilerlistenzuordnung geändert.
Zwei Sonderfälle gibt es noch beim Ändern von Abonnentendaten:
- Das Verändern der Email-Adresse benötigt einen speziellen Parameter: NEWEMAIL
- Die Zuordnung von Verteilerlisten kann in zwei Arten erfolgen: Absolut oder Additiv. Um Verteilerlisten additiv zuzuordnen, ist die Parameterliste um den Parameter CHANGETYPE=1 zu erweitern.
Ändern der Email-Adresse:
http://domain.kunde.de/bc/servlet/web.httpapi?EMAIL=abc@def.gh&NACHNAME=Mustermann&VORNAME=Max&NEWEMAIL=xyz@xyz.zz&MID=0
Ändern der Daten mit absoluter Verteilerlistenzuordnung:
http://domain.kunde.de/bc/servlet/web.httpapi?EMAIL=abc@def.gh&NACHNAME=Mustermann&VORNAME=Max&PASSWORD=123456&NEWSLETTER=1;2;3&MID=0
Hier werden dem Abonnenten die Verteilerlisten 1, 2 und 3 zugeordnet. Eventuelle andere, bestehende Zuordnungen werden gelöscht.
Ändern der Daten mit additiver Verteilerlistenzuordnung:
http://domain.kunde.de/bc/servlet/web.httpapi?EMAIL=abc@def.gh&NACHNAME=Mustermann&VORNAME=Max&PASSWORD=123456&NEWSLETTER=4;6&CHANGETYPE=1&MID=0
Hier werden dem Abonnenten die Verteilerlisten 4 und 6 zusätzlich, zu bereits vorhandenen anderen Listen, zugeordnet.
Außerdem kann noch der Parameter SENDCONFIRM angegeben werden. Dies veranlasst BACKCLICK dazu, Begrüßungs- und Verabschiedungsemails zu versenden. Der Text dieser Emails wird in der Konfiguration der entsprechenden Verteilerliste festgelegt. Diese Zusendung gilt sowohl für An- als auch für Abmeldungen.
Löschen eines Abonnenten
Sie können Abonnenten auch jederzeit aus dem System entfernen oder nur einzelne Abonnements von Verteilerlisten löschen.
In jedem Fall müssen Sie die Email-Adresse des zu löschenden Abonnenten und den Parameter DELETE=1 angeben.
http://domain.kunde.de/bc/servlet/web.httpapi?EMAIL=abc@def.gh&DELETE=1&MID=0
In diesem Fall wird der Abonnent mit allen vorhandenen Abonnements aus dem System entfernt.
http://domain.kunde.de/bc/servlet/web.httpapi?EMAIL=abc@def.gh&NEWSLETTER=1&DELETE=1&MID=0
In diesem Fall wird nur das Abonnement für die Verteilerliste mit der ID=1 gekündigt.
Zusätzliche Parameter
Zusätzlich kann noch der Parameter SENDCONFIRM angegeben werden. Dies veranlasst BACKCLICK dazu, Begrüßungs- und Verabschiedungs-Emails zu versenden. Der Text dieser Mails wird in der Konfiguration der entsprechenden Verteilerliste festgelegt. Diese Zusendung gilt sowohl für An- als auch für Abmeldungen.
Beispiel:
http://domain.kunde.de/bc/servlet/web.httpapi?EMAIL=abc@def.gh&DELETE=1&SENDCONFIRM=1&MID=0
In diesem Fall erhält der Abonnent für jede abgemeldete Verteilerliste eine Abmeldebestätigung. Vorausgesetzt diese Meldung ist dort definiert.
Statusmeldungen der API
Fehlercodes:
-1 --> angegebene Email-Adresse ist syntaktisch falsch (RFC Email Check fehlgeschlagen)
-2 --> keine korrekte NEUE Email-Adresse eingegeben bei Änderung der Abonnenten-Email (RFC Email Check fehlgeschlagen)
-3 --> keine Email-Adresse angegeben
-4 --> kein NEWSLETTER-Parameter in URL vorhanden
-5 --> Email-Adresse ist nicht im System vorhanden bei Änderung der Abonnenten-Email-Adresse
-6 --> zurzeit keine Datenbankverbindung zwischen API Server und DBMS möglich
-7 --> übergebene NEWSLETTER-Parameter entweder leer oder nicht vorhandene ListenID angegeben
-8 --> kein Passwort angegeben oder falsches Passwort eingegeben
-9 --> Abonnent ist auf der BACKCLICK internen Robinsonliste vorhanden
-10 --> Funktion ist aus lizenztechnischen Gründen deaktiviert
-11 --> Fehler beim unsubscribe aufgetreten, eventuell noch einmal versuchen
-12 --> beim unsubscibe ist die abzumeldende Email-Adresse nicht auf einer der übergebenen ListenID abonniert
-100 --> HTTP-API Funktion in Systemeinstellungen deaktiviert, müsste aktiviert werden
Successcodes:
OK2 --> Abonnent erfolgreich gelöscht
OK3 --> Abonnent erfolgreich gelöscht
OK4 --> Abonnent erfolgreich angelegt
OK5 --> Abonnentendaten erfolgreich geändert