Schnittstelle zum externen Update von Empfängerdaten


Schnittstelle zum externen Update von Abonnenten-Daten

Der folgende Artikel beschreibt das Update von Empfängerdaten, um z.B. Datenfelder einzelner Empfänger direkt aus Ihrer Webanwendung heraus zu ändern.

Diese Anleitung ist für Entwickler und Programmierer gedacht und setzt entsprechende Kenntnisse voraus.

Mithilfe dieser Schnittstelle können Sie die Inhalte von Datenfeldern, die bei Ihren Empfängern gespeichert sind, direkt verändern.

Dazu müssen die zu ändernden Datenfelder und deren Werte per POST-Request (mit Content-Type: application/x-www-form-urlencoded) an diese URL übergeben werden:

https://xyz.frnl.de/api/subscriber/
(http ist ebenfalls möglich, aus Sicherheitsgründen aber nicht empfehlenswert)

xyz ersetzen Sie bitte durch die Nummer Ihres Servers, die Zahl ist identisch zu der in Ihrer Login-Adresse zum Control Center.

Parameter  * kennzeichnet Pflichtfelder
user *
Ihr Benutzername
list *
die ID der Liste, in der der Empfänger gespeichert ist. Sie finden die ID der Liste u.a. im Control Center, ganz oben bei "Aktuelle Liste: Listenname (ID: 1234)"
email *
die Email-Adresse des abzufragenden Empfängers
hash *
der Sicherheitshash. MD5-Hash aus Email-Adresse, Listen-ID und einem geheimen Schlüssel. Den geheimen Schlüssel vereinbaren Sie bitte vor der ersten Nutzung der API mit uns.
PHP-Beispiel-Code:

$hash = md5($email.$list.$secret)
name Name des Empfängers. name ist ein Systemfeld, d.h. es ist bei jedem Empfänger automatisch vorhanden
fx f (für "field") mit folgender ID des zu ändernden Datenfeldes
Zusätzlich angelegte Datenfelder sind in jeder Liste mit einer ID-Nummer hinterlegt. So könnte z.B. die ID des Datenfeldes "Vorname" in Ihrer Liste "123" sein. Die jeweilige ID übernehmen Sie einfach aus dem HTML-Code Ihres Formulares.
Beispiel:
HTML-Code im Anmeldeformular:
<td>Vorname</td><td><input type='text' name='field[<font color="#FF0000">123</font>,0]' value='' /></td>
Um den Vornamen zu ändern. ist also der Parameter f123 zu übergeben
  • Um mehrere Datenfelder zu ändern, übergeben Sie einfach alle gewünschten Datenfelder mit den Werten in einer Abfrage:
    f123=Max&name=Mustermann&f234=Hamburg
  • Soll der Inhalt von Checkboxen-Feldern geändert werden, übergeben Sie den Wert "checked" für eine markierte Checkbox und "unchecked" für eine inaktive Checkbox

Wichtig:

Übergeben Sie Zeichenketten aus Benutzereingaben, wie z.B. "name" und andere Datenfelder immer URL-kodiert, damit Leer- und Sonderzeichen in URL-taugliche Zeichen umgewandelt werden. Ein Leerzeichen " " wird damit z.B. zu " " umgewandelt.

PHP: rawurlencode($string)
[removed] encodeURIComponent(string)
Python 2.x: (import urllib) urllib.quote(string)
Python 3.x (import urllib.parse) urllib.parse.quote(string)
Ruby: CGI.escape(string)


Beispiel:
Um Daten für die Emailadresse "test@example.com" in einer Liste mit der ID 555 zu ändern:

URL: http://123.frnl.de/api/subscriber/
POST body:
list=555&hash=0cefb38d0dda115b213353ff2196f390&email=test@example.com&user=testuser&name=Mustermann&f123=Max&f234=Frankfurt am Main


Bei Erfolg erhalten Sie den kompletten neuen Datensatz des Abonnenten im JSON-Format in der Form zurück:


{
    "ID": "12345678",
    "Email": "test@example.com",
    "Name": "Mustermann",
    "subscribe_date": "2009-12-31",
    "subscribe_time": "13:14:15",
    "subscribe_ip": "12.34.56.78",
    "Vorname": "Max"

    "Ort": "Frankfurt am Main"
}


Leere Felder, d.h. nicht vergebene Datenfelder,  enthalten als Wert "null".

Rückgabewerte  
ID die interne ID der Email-Adresse
Email die Email-Adresse
Name der Name des Empfängers
subscribe_date Datum der Anmeldung im ISO-8601 Format
subscribe_time Uhrzeit der Anmeldung
subscribe_ip IP-Adresse, von welcher die Anmeldung erfolgte
weitere Feldnamen jedes angelegte Zusatzdatenfeld wird bei Vorhandensein von Werten ebenfalls ausgegeben

Bei einem Fehler erhalten Sie die Rückgabe im JSON-Format in der Form:

{
    "Error": {
        "Fehler-ID": "Fehlermeldung im Klartext"
    }
}

Hinweise: