Rubrik: Schnittstellen / API, Formulare, An- und Abmelden, Einbindung in die Webseite

Schnittstelle für externe Webanwendungen zum Ein- und Austragen ohne Formular

| Drucken |
Dieser Artikel beschreibt die Übergabe von Daten per GET oder POST direkt an die Datenbank, um z.B. Adressdaten direkt aus Ihrer Webanwendung, wie CMS oder Shopsystem, an Ihre Liste bei Flatrate Newsletter zu übergeben.

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

Erstellen Sie sich zuerst ein Anmeldeformular in Ihrer Liste über den Menüpunkt "Integration > Anmeldeformulare".
Über das Anmeldeformular bzw. dessen ID werden unter anderem auch die Bestätigungsseiten gesteuert.

Sie können die Daten per GET oder POST an den Formularhandler übergeben. Für die Übergabe per GET hängen Sie die Parameter einfach an die URL an, für die Übergabe per POST nutzen Sie z.B. cURL um die Daten an den Formularhandler zu posten.

Im HTML-Code des Anmeldeformulares finden Sie alle benötigten Variablen und Werte, die Sie übergeben müssen.
  1. URL: http://123.frnl.de/box.php
    (entspricht dem "action"-Parameter aus dem form-Tag, die Subdomain (hier als Beispiel 123) ist identisch zu der Ihres Control Centers)

  2.  p: Formular-ID, ganzzahliger Wert, z.B. "101",
    über die Formular-ID werden u.a. die nach der Aktion angezeigten Bestätigungsseiten gesteuert

  3. funcml: steuert Anmelden oder Abmelden
    Wert für Anmelden: "add"
    Wert für Abmelden: "unsub2"

  4. nlbox[x]: Die ID der Liste, ganzzahliger Wert z.B. "123"
    x ist normalerweise "1" -  sollen allerdings Adressen gleichzeitig in mehrere Listen eingetragen werden, muss nlbox[x] mehrfach übergeben werden, z.B. "nlbox[1]=100&nlbox[2]=101"

  5. email: die Email-Adresse
    wird überprüft und nur bei korrekter Syntax angenommen.  Falls Sie ungeprüfte Adressen übergeben, sollten Sie die Rückgabe auf Fehlercodes parsen

  6. name: Name des Abonnenten, beliebiger Text

  7. field[xyz,a] individuelle Datenfelder,beliebiger Text
    Mittels des field[ ]-Arrays werden Ihre selbst angelegten Datenfelder übertragen, übernehmen Sie einfach die entsprechenden Parameter aus dem HTML-Code Ihres Formulares.

  8. [optional] skip_doi: Anweisung zur Deaktivierung des Double-Opt-In-Verfahrens
    Möglicher Wert: "true" bzw. "1" (funktionsgleich)
    Mit dem Parameter "skip_doi=true" (oder "skip_doi= 1") kann ein in der Liste eingestelltes Double-Opt-In-Verfahren für die einzelne Anmeldung deaktiviert werden. Der Empfänger wird damit also direkt - wie beim Single-Opt-In  ohne weitere Bestätigung - in die Liste eingetragen, auch wenn in der Liste das Double-Opt-In-Verfahren aktiv ist. D.h. es wird auch nicht die übliche Email mit dem Bestätigungslink versendet.
    Bitte verwenden Sie diesen Parameter nur, wenn Sie Adressen eintragen, die bereits über Ihr System nachweisbar gesetzeskonform per Double-Opt-In verifiziert wurden (z.B. über eine Anmeldung in einem Shop, Forum etc.).

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)

Beispiele:
Um die Emailadresse "test@example.com" und den Namen "Max Mustermann" mit Anrede "Herr" einzutragen, würden Sie folgende URL aufrufen:

http://123.frnl.de/box.php?email=test@example.com&name=Max Mustermann&field[789,0]=Herr&p=123&nlbox[1]=456&funcml=add


Zum Abmelden einer Emailadresse genügt die Übergabe der Emailadresse, Name und andere Datenfeler sind nicht nötig:
http://123.frnl.de/box.php?email=test@example.com&p=123&nlbox[1]=456&funcml=unsub2

Zeichenkodierung
Zur korrekten Übergabe von Umlauten und Sonderzeichen übergeben Sie die Daten bitte in UTF-8 Kodierung. Falls das nicht möglich ist, übergeben Sie das Character-Set  Ihrer Werte mit dem Parameter "_charset", z.B. "&_charset=ISO-8859-1". Damit wird unser System angewiesen, die von Ihnen verwendete Kodierung in das von unserem Server verwendete UTF-8 zu konvertieren.

Rückgabewerte
Nach erfolgreicher Übermittlung erfolgt eine HTTP 302 Weiterleitung auf die im Formular angegebene Bestätigungsseite. An die URL der Bestätigunsseite sind die Listen als Parameter "lists" und die Bestätigungscodes als Parameter "codes" angehängt (jeweils kommagetrennt, falls mehrere Listen betroffen sind)
Die URL der Bestätigungsseite kann z.B. mit PHP und "curl_getinfo" ausgelesen werden:
(Beispielcode, ohne Fehlerbehandlung)

<?php
// URL zum Eintrag eines Abonnenten aufrufen
$c = curl_init();
curl_setopt($c, CURLOPT_URL, "http://123.frnl.de/box.php?email=test@example.com&name=Max Mustermann&p=1234&nlbox[1]=5678&funcml=add");
curl_exec($c);
// Transfer-Info auslesen
$response_info = curl_getinfo($c);
curl_close($c);

// URL der Bestätigungsseite "redirect_url" auswerten
$urlparts = parse_url($response_info['redirect_url']);
$query = $urlparts['query'];
parse_str($query);
echo $codes;
?>


Die Legende der Rückgabewerte ("codes"):

'1'=> 'Diese Versandliste kann leider momentan keine neuen Abonnenten aufnehmen. Die maximale Anzahl an Abonnenten wurde erreicht.',
'2'=> 'Ihre Anmeldung konnte nicht bearbeitet werden, da Pflichtfelder keine Daten enthielten.',
'3'=> 'Die Email-Adresse ist bereits auf dieser Liste eingetragen.',
'4'=> 'Diese Email-Adresse wurde in der Vergangenheit schon angemeldet, jedoch hat der Empfänger den Eintrag nie bestätigt.',
'5'=> 'Diese Email-Adresse kann der Liste nicht hinzugefügt werden.',
'6'=> 'Die Email-Adresse wurde verarbeitet. Bitte sehen Sie nun in Ihrem Email-Eingang nach, um die Anmeldung zu bestätigen.',
'7'=> 'Die Email-Adresse wurde der Versandliste hinzugefügt.',
'8'=> 'Die Email-Adresse ist ungültig.',
'9'=> 'Die Anmeldung konnte nicht bearbeitet werden, weil keine Liste ausgewählt war. Bitte wählen Sie eine Liste aus.',
'10'=> 'This e-mail address has been processed.  Please check your email to confirm your unsubscription.',
'11'=> 'Die Email-Adresse wurde von der Versand-Liste entfernt.',
'12'=> 'Die Email-Adresse wurde der Versand-Liste nicht hinzugefügt.',
'13'=> 'Vielen Dank für die Bestätigung Ihrer Anmeldung.',
'14'=> 'Vielen Dank für die Bestätigung Ihrer Abmeldung.',
'15'=> 'Ihre Änderungen wurden gespeichert.',
'16'=> 'Ihre Anmeldung konnte nicht bearbeitet werden, da kein Name angegeben war.',
'17'=> 'Die Email-Adresse befindet sich auf der globalen Ausschlussliste.',
'18'=> 'Bitte geben Sie exakt den Text ein, der im Bild erscheint.',


Sie können die Schnittstelle im Hintergrund Ihrer Webanwendung aufrufen, mit PHP beispielsweise per fopen(), file_get_contents() oder mithilfe der cURL-Bibliothek oder auch über ein <img> Tag aufrufen. Letzteres empfehlen wir aus Gründen der Datensicherheit aber nicht.

Für Sonderwünsche oder spezielle Fragen kontaktieren Sie uns bitte - wir haben schon für eine Vielzahl von Anwendungen spezielle Schnittstellen und Lösungen für unsere Kunden geschaffen.

War dieser Artikel hilfreich?

Ja Nein