Newsletter2Go - API Dokumentation

Transkript

1 Newsletter2Go - API Dokumentation Changelog: (version 1.1 version 1.2) - Funktion "Gruppen abrufen" hinzugefügt - Funktion "Spezifische Merkmale abrufen" hinzugefügt - Funktion "Formular key generieren" hinzugefügt - neue Statuscodes hinzugefügt (version 1.0 version 1.1) - Zwei neue optionale Parameter (opentracking, linktracking) in versenden Funktion (version 0.9 version 1.0) - category ist neuer notwendiger Parameter beim Versenden einer - Funktion "Newsletter erstellen" hinzugefügt - Funktion "Statistiken abrufen" hinzugefügt - Funktion "Empfänger erstellen" hinzugefügt - neue Statuscodes hinzugefügt Inhalt 2. Rückgabewerte 3. Statuscodes 4. Versenden einer 5. Versenden einer SMS 6. Erstellen eines Newsletters 7. Statistiken abrufen 8. Empfänger erstellen 9. Gruppen abrufen 10. Spezifische Merkmale abrufen 11. Formular generieren (Key)

2 Mit der Newsletter2Go API können Sie die wesentlichen Funktionalitäten von Newsletter2Go in Ihre Anwendung integrieren. Die API wird über das REST-Protokoll realisiert. Sämtliche HTTP-Aufrufe müssen per POST durchgeführt werden. Die Rückgabewerte erfolgen stets im JSON-Format. Bei jeder HTTP-Anfrage müssen alle POST-Daten url-encoded übergeben werden, um eine korrekte Übertragung und Verarbeitung gewährleisten zu können. Sämtliche API-Anfragen müssen über das SSL-Protokoll (HTTPS) laufen. Anfragen ohne SSL sind nicht möglich. 2. Rückgabewerte Sämtliche Rückgabewerte der Newsletter2go API erfolgen im JSON Format (application/json). Es wird immer genau ein JSON-Objekt zurückgegeben, welches immer genau vier key-value-paare besitzt: valueexample description key value-type success int 0 or 1 1 means success, 0 means fail value String or null status int 200 returns a value in case of requests that will give a result, e.g. a newsletter id. Note: this is always a string, even if a number is returned. This is null, if no value is returned. The status code which defines the response. For status code explanations see status codes. reason String 'OK' A textual representation of the status code. Ein Beispiel für ein resultierendes JSON-Objekt wäre: { } success:0, value:null, status:405, reason:"method Not Allowed, POST Requiered"

3 3. Statuscodes Die zurückgegebenen Statuscodes orientieren sich an den HTTP- Statuscodes. 200 => 'OK' 201 => 'Created' 400 => 'Bad Request' 401 => 'Unauthorized' 402 => 'Not enough credits' 405 => 'Method Not Allowed, POST required' 419 => 'at least 1 required param missing' 420 => 'unknown error' 421 => 'type has wrong value' 422 => '"from" value required' 423 => 'category has to be "basic" or "plus"' 425 => 'name is empty' 426 => 'date has bad value' 427 => 'date is too big (only one year allowed)' 428 => 'Newsletter ID has bad value' 429 => 'at least one address is not valid' 430 => 'not allowed to send yet' 431 => 'no statistics allowed for this newsletter (must be sent or created with api)' 432 => 'newsletter id does not belong to you or it does not exist' 433 => 'optional statistics parameter value has to be 0,1,true,false' 434 => 'recipient needs or mobile' 435 => 'gender has to be m or f' 436 => 'at least one url is not valid' 437 => 'group id must be a number and greater than 0' 438 => 'group does not exist' 500 => 'Internal Server Error'

4 4. Versenden einer 3. Optionale Parameter 4.1 Allgemeines Die REST-API für unsere Newsletter Software Newsletter2Go Um über die Newsletter2Go API eine versenden zu können, setzen Sie aus Ihrer Anwendung einen POST Request via HTTPS Protokoll an folgende URL: ab Notwendige Parameter Sämtliche Parameter müssen url-encoded übergeben werden. Folgende Parameter sind notwendig, um eine über die Schnittstelle zu versenden. Die Reihenfolge der Parameter ist beliebig. Die Parameter sind case-sensitive. Das keyword muss in Kleinbuchstaben übergeben werden. key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd1ddb4cc2f85cedasd54fccc4a4d8 "Konto". to Die Empfänger- adresse from Die Absender- -Adresse subject Der Betreff der Ihre Bestellung vom html Der komplette HTML-Quellcode <html><body>hallo Freunde,<br/>...</body></html> text Der Text-Part der Hallo Freunde, category Die Kategorie der . Es stehen basic und plus zur Auswahl basic 4.3 Optionale Parameter Default-Wert Die id des Newsletters bei id Newsletter2Go. Sie wird benötigt, falls Sie die Reporting-Funktionen von 1453 null

5 Newsletter2Go über die API nutzen möchten. debug Mit 1 Einschalten des Debug-Modus. Ist der Debug-Modus eingeschaltet, können Sie die API von Newsletter2go testen, 1 0 ohne dass die tatsächlich versendet wird. ref Eine eigene Referenz, die Sie beliebig wählen können. Januar2011 null Versenden der zeitversetzt. Es muss ein UNIX-Timestamp übergeben werden. Liegt der Timestamp in der date Vergangenheit, ist er negativ oder leer Die aktuelle Zeit wird sofort versendet. Wird kein valider der Einlieferung UNIX-Timestamp übergeben, wird die der nicht entgegengenommen und Fehlercode 420 wird zurück gegeben. Der Timestamp darf maximal 1 Jahr in der Zukunft liegen. Sie können eine alternative Replyreply Adresse angeben. Das ist die - Die from- Adresse, an die eine geschickt noreply@example.org Adresse. wird, wenn der Empfänger auf "antworten" klickt. An- bzw. Abschalten des Linktrackings. Standardmäßig ist diese Option eingschaltet. Wird das Linktracking linktracking abgeschaltet, werden Links nicht false 1 umgeschrieben und damit können Klicks auf Links nicht registriert werden. An- bzw. Abschalten des Öffnungs- Tracking. Standardmäßig ist diese Option opentracking eingeschaltet. Wird das Opentracking abgeschaltet, werden Öffnungen der s nicht registriert. 0 1

6 5. Versenden einer SMS 3. Optionale Parameter 5.1 Allgemeines Um über die Newsletter2Go API eine SMS versenden zu können, setzen Sie aus Ihrer Anwendung einfach einen POST Request via HTTPS Protokoll an folgende URL: Notwendige Parameter Sämtliche Parameter müssen url-encoded übergeben werden. Folgende Parameter sind notwendig, um eine SMS über die Schnittstelle zu versenden. Die Reihenfolge der Parameter ist beliebig. Die Parameter sind case-sensitive. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn acbd18db4cc2f85csdef654fccc4a4d8 in Ihrem Account unter "Konto". to Die Empfänger-Mobilfunknummer message Der Text der Nachricht. Maximal sind 1530 Lieber Peter, ich freue mich, dass... Zeichen möglich. category Die Kategorie der SMS. Es stehen basic und basic plus zur Auswahl 5.3 Optionale Parameter Default-Wert from Dies ist die Absenderkennung der SMS. Nur relevant, falls category = plus. Die Absenderkennung darf maximal 11 alphanumerische oder 16 numerische Zeichen enthalten. Hinweis: Verzichten Sie auf Meine Firma Sonderzeichen jeglicher Art, da sie nicht auf jedem Mobilfunkgerät uneingeschränkt dargestellt werden. id Die id des Newsletters bei Newsletter2Go. Sie wird 1453 benötigt, falls Sie die Reporting-Funktionen von null

7 debug ref date Newsletter2Go über die API nutzen möchten. Mit 1 Einschalten des Debug-Modus. Ist der Debug-Modus eingeschaltet, können Sie die API von Newsletter2go testen, ohne dass die SMS tatsächlich versendet wird. Eine eigene Referenz, die Sie beliebig wählen können. Versenden der SMS zeitversetzt. Es muss ein UNIX-Timestamp übergeben werden. Liegt der Timestamp in der Vergangenheit, ist er negativ oder leer wird sofort versendet. Wird kein valider UNIX-Timestamp übergeben, wird die SMS nicht entgegengenommen und Fehlercode 420 wird returned. 1 0 SMS- Angebot null Die aktuelle Zeit der Einlieferung der SMS. 6. Erstellen eines Newsletters 6.1 Allgemeines Um einen Newsletter über die Newsletter2Go API zu erstellen, setzten Sie einen POST Request über HTTPS an folgende URL: Dabei ist zu beachten, dass diese Funktion nur dazu da ist, eine Newsletter ID zu erzeugen und zurückzuliefern. 6.2 Notwendige Parameter Sämtliche Parameter müssen url-encoded übergeben werden. Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Die Reihenfolge der Parameter ist beliebig. Die Parameter sind case-sensitive. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2f85cedef654fccc4a4d8 "Konto". name Name des Newsletters (nicht der Newsletter 2011 Nr. 1

8 type category Betreff) Der Typ des Newsletters. Es stehen sms und zur Auswahl Die Kategorie der SMS. Es stehen basic und plus zur Auswahl sms basic Im zurückgegebenen JSON Objekt wird in dem value Feld die erzeugte Newsletter_ID zurückgeliefert. 7. Statistiken abrufen 3. Optionale Parameter 7.1 Allgemeines Um für einen Newsletter Statistiken abzurufen, setzen Sie einen POST Request über HTTPS an folgende URL: Das Antwort-JSON-Objekt enthält in dem value-feld ein zweites JSON- Objekt, welches die Statistik-Werte enthält. Da es sich um Verhältnis-zahlen handelt, liegen sie zwischen 0 und 1 (z.b. 0.3 entspricht dann 30%). Es ist aber auch denkbar, dass ein Wert größer als 1 zurückgegeben wird (z.b. 2 entspricht dann 200%) Die Bezeichnungen der Statistikwerte entsprechen den optionalen Parametern. 7.2 Notwendige Parameter Sämtliche Parameter müssen url-encoded übergeben werden. Folgende Parameter sind notwendig, um die Statistiken eines Newsletters abzurufen. Die Reihenfolge der Parameter ist beliebig.

9 Die Parameter sind case-sensitive. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2f85cedasd54fccc4a4d8 "Konto". Id Die Newsletter-ID 3 Es sind nur Newsletter-Ids erlaubt, die zu Ihrem Account gehören. 7.3 Optionale Parameter Hier können Sie wählen, welche Statistik-Werte Sie abrufen wollen. Geben sie keine dieser Parameter an, dann werden standardmäßig alle Statistik- Werte zurückgegeben. Die Auswahl der Statistik erfolgt über einen boolschen Wert (0,1,true,false), wobei 1 und true bedeuten, dass der Wert zurückgegeben werden soll und 0 bzw. false bedeuten, dass er nicht zurückgeliefert wird. recipients Anzahl der Empfänger für den 0 Newsletter uniqueopenrate eindeutige Öffnungsrate 1 openrate Öffnungsrate (enthält mehrfache Öffnungen) true notopenrate Verhältnis Nicht-Öffnungen zur Gesamt-Empfängerzahl false uniqueclickrate eindeutige Klickrate FALSE clickrate Klickrate (enthält mehrfache Klicks) TRUE notclickrate Verhältnis von Empfängern die nicht geklickt haben zur 1 Gesamt-Empfängerzahl bouncerate Bounces im Verhältnis zur Gesamt-Empfängerzahl 1 deliveryrate Gesamt-Empfängerzahl - Bounces (Differenz) 0 Für SMS-Newsletter ist nur der recipients-parameter möglich.

10 8. Empfänger erstellen 3. Optionale Parameter 8.1 Allgemeines Sie können mit dieser Funktion Ihrem Newsletter2Go-Adressbuch neue Empfänger hinzufügen. Dies ist sinnvoll, wenn Sie z.b. automatisiert Ihr Shopsystem mit Ihrem Newsletter2Go-Adressbuch synchronisieren wollen. Wichtig: um s oder SMS über diese API zu versenden, brauchen Sie keine Empfänger vorher anzulegen. Um einen Empfänger zu erstellen bzw. zu ihrem Adressbuch hinzuzufügen, setzten Sie einen Post Request über HTTPS an folgende URL: Notwendige Parameter key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2as5cedef654fccc4a4d8 "Konto". -Adresse des Empfängers mobile Handynummer des Empfängers Es ist mindestens ein Parameter von und mobile nötig. Es können aber auch beide Parameter angegeben werden. 8.3 Optionale Parameter lastname Nachname des Empfängers Mustermann firstname Vorname des Empfängers Max gender Geschlecht des Empfängers (m oder f) m

11 group1 Gruppenzugehörigkeit des Empfängers Informatiker group2 Weitere Gruppenzugehörigkeiten Fußballer Haarfarbe Spezifische / Eigene Attribute weiß Schuhgroes Weitere Attribute se 43 Die REST-API für unsere Newsletter Software Newsletter2Go Es können beliebig viele Gruppen und Attribute angegeben werden. Die Schlüssel für Gruppen müssen group enthalten. Diese Schlüssel müssen durchnummeriert werden. Ein Attribut-Name darf nicht das Wort group enthalten. Attributnamen dürfen keine Umlaute oder Sonderzeichen enthalten. Beispiel-JSON { key : acbd18db4cc2asdcedef654fccc4a4d8, test@example.org, firstname : Konrad, group1 : Informatiker, group2: Handballer, Haarfarbe : schwarz, Bewertung : 4 } Sind Attribute (z.b. Haarfarbe) nicht vorhanden, so werden sie neu angelegt. Dasselbe gilt für Gruppen. 9. Gruppen abrufen 9.1 Allgemeines Um Ihre Gruppen über die Newsletter2Go API abzurufen, setzten Sie einen POST Request über HTTPS an folgende URL:

12 9.2 Notwendige Parameter Sämtliche Parameter müssen url-encoded übergeben werden. Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Die Reihenfolge der Parameter ist beliebig. Die Parameter sind case-sensitive. Das keyword muss in Kleinbuchstaben übergeben werden! Ihr Newsletter2Go API-Key. Sie key finden ihn in Ihrem Account unter "Konto". acbd18db4cc2f85cedef654fccc4a4d8 Diese Funktion benötigt nur den Api-Key und liefert die Gruppen Identifier (ID) und die dazugehörigen Namen. 10. Spezifische Merkmale abrufen 10.1 Allgemeines Um Ihre Attribute über die Newsletter2Go API abzurufen, setzten Sie einen POST Request über HTTPS an folgende URL: Notwendige Parameter Sämtliche Parameter müssen url-encoded übergeben werden. Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Die Reihenfolge der Parameter ist beliebig. Die Parameter sind case-sensitive. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie acbd18db4cc2f85cedef654fccc4a4d8

13 finden ihn in Ihrem Account unter "Konto". Die REST-API für unsere Newsletter Software Newsletter2Go Diese Funktion benötigt nur den Api-Key und liefert die Attribut Identifier und die dazugehörigen Namen. 11. Formular erstellen (Key) 3. Optionale Parameter 11.1 Allgemeines Um einen Formular-Key über die Newsletter2Go API zu erstellen, setzen Sie einen POST Request über HTTPS an folgende URL: Notwendige Parameter Sämtliche Parameter müssen url-encoded übergeben werden. Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Die Reihenfolge der Parameter ist beliebig. Die Parameter sind case-sensitive. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2f85cedef654fccc4a4d8 "Konto". host Der Host der Domain,auf dem das Formular eingesetzt wird. Ohne example.org Subdomains oder Unterverzeichnisse. from Die Absender- -Adresse der der Opt-In- . subject Betreff der Opt-In- Newsletter-Anmeldung bei meine-hp.de html Der Html-Inhalt der Opt-In <html>danke für die Anmeldung zum Newsletter bei meine-hp.de</html> group Die ID der Gruppe, in die neue Anmeldungen eingeordnet werden. ( -1 = keine Gruppe) 4

14 11.3 Optionale Parameter Mit diesen Parametern können sie zusätzliche Informationen zu ihrem Formular angeben. successpage failpage dupentrypage Die URL der Seite, auf die nach Klick auf den Link in der Opt-In- umgeleitet wird. Die URL der Seite, die aufgerufen wird, falls ein Fehler auftritt. Die URL der Seite, die aufgerufen wird, falls die angemeldete -Adresse bereits existiert. cess r licate Default-Wert reply Antwort-Adresse der Opt-In , an die mögliche Fragen reply@example.org die from-adresse gesendet werden können Die URL der Seite, auf die landingpage direkt nach dem Absenden des Formulars umgeleitet werden scribe soll Dieser Aufruf gibt nur den Code zurück, der im Anmeldeformular per nl2go--key übergeben werden muss. Es wird kein richtiges Formular erzeugt, sondern nur der Key und die übergebenen Parameter werden in die Datenbank geschrieben. Das Formular kann dann noch freier gestaltet werden. Die Eingabe-Elemente müssen aber dieselben Bezeichnungen haben, die Newsletter2Go vorschreibt. Daher ist es Ihnen dringend empfohlen, sich ein Formular über den Formular-Generator auf newsletter2go.de erstellen zu lassen (in Ihrem Account unter Einstellungen).