Newsletter2Go - API Dokumentation Changelog: (version 1.2 version 1.3) - Funktion "Attribut setzen" hinzugefügt - Funktion "Newsletter abrufen" hinzugefügt - Funktion "Webversion-Link abrufen" hinzugefügt - neue Statuscodes hinzugefügt (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 Email versenden Funktion (version 0.9 version 1.0) - category ist neuer notwendiger Parameter beim Versenden einer Email - 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 Email 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) 12. Attribut setzen 13. Newsletter abrufen 14. Webversion-Link abrufen
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. 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 email 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 email 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' 439 => 'attribute does not exist' 440 => 'recipient does not exist' 441 => 'recipient already exist' 500 => 'Internal Server Error'
4. Versenden einer Email 3. Optionale Parameter 4.1 Allgemeines Um über die Newsletter2Go API eine E-Mail versenden zu können, setzen Sie aus Ihrer Anwendung einen POST Request via HTTPS Protokoll an folgende URL: ab. https://www.newsletter2go.de/de/api/send/email/ 4.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Email über die Schnittstelle zu versenden. Das keyword muss in Kleinbuchstaben übergeben werden. key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd1ddb4cc2f85cedasd54fccc4a4d8 to Die Empfänger-Emailadresse recipient@example.org from Die Absender-Email-Adresse ihreadresse@ihredomain.de subject Der Betreff der Email Ihre Bestellung vom 23.05.2011 html Der komplette HTML-Quellcode <html><body>hallo Freunde,<br/>...</body></html> text Der Text-Part der Email Hallo Freunde, category Die Kategorie der Email. 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
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, 1 0 ohne dass die Email tatsächlich versendet wird. Eine eigene Referenz, die Sie beliebig wählen können. Januar2011 null Versenden der Email zeitversetzt. Es muss ein UNIX-Timestamp übergeben werden. Liegt der Timestamp in der Vergangenheit, ist er negativ oder leer Die aktuelle Zeit wird sofort versendet. Wird kein valider 1306351118 der Einlieferung UNIX-Timestamp übergeben, wird die der Email Email nicht entgegengenommen und Fehlercode 420 wird zurück gegeben. Der Timestamp darf maximal 1 Jahr in der Zukunft liegen. Sie können eine alternative Reply- Adresse angeben. Das ist die Emailreply Adresse, an die eine Email geschickt 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 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 Emails nicht registriert. noreply@example.org false 1 0 1 Die from- Adresse.
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: https://www.newsletter2go.de/de/api/send/sms/ 5.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine SMS über die Schnittstelle zu versenden. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn acbd18db4cc2f85csdef654fccc4a4d8 in Ihrem Account unter to Die Empfänger-Mobilfunknummer +49 178 1234567890 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
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 1306351118 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: https://www.newsletter2go.de/de/api/create/newsletter/ Dabei ist zu beachten, dass diese Funktion nur dazu da ist, eine Newsletter ID zu erzeugen und zurückzuliefern. 6.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2f85cedef654fccc4a4d8 name Name des Newsletters (nicht der Newsletter 2011 Nr. 1
type category Betreff) Der Typ des Newsletters. Es stehen sms und email 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: https://www.newsletter2go.de/de/api/get/statistics/ 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 Folgende Parameter sind notwendig, um die Statistiken eines Newsletters abzurufen.
Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2f85cedasd54fccc4a4d8 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.
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 Emails 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: https://www.newsletter2go.de/de/api/create/recipient/ 8.2 Notwendige Parameter key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2as5cedef654fccc4a4d8 email Email-Adresse des Empfängers recipient@domain.de mobile Handynummer des Empfängers 0123456789 Es ist mindestens ein Parameter von email 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
group1 Gruppenzugehörigkeit des Empfängers Informatiker group2 Weitere Gruppenzugehörigkeiten Fußballer Haarfarbe Spezifische / Eigene Attribute weiß Schuhgroes Weitere Attribute se 43 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, email : 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:
https://www.newsletter2go.de/de/api/get/groups/ 9.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Das keyword muss in Kleinbuchstaben übergeben werden! Ihr Newsletter2Go API-Key. Sie key finden ihn in Ihrem Account unter 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: https://www.newsletter2go.de/de/api/get/attributes/ 10.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie acbd18db4cc2f85cedef654fccc4a4d8
finden ihn in Ihrem Account unter 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 ein Formular key über die Newsletter2Go API zu erstellen, setzten Sie einen POST Request über HTTPS an folgende URL: https://www.newsletter2go.de/de/api/create/form/ 11.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Das keyword muss in Kleinbuchstaben übergeben werden! key Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter acbd18db4cc2f85cedef654fccc4a4d8 host Der Webseitenname, auf dem das Formular eingesetzt wird http://www.meine-hp.de from Die Absender-Email-Adresse mein.name@example.org subject Betreff der Opt-In Email Newsletter-Anmeldung bei meine-hp.de html Der Html-Inhalt der Opt-In Email <html>danke für die Anmeldung zum Newsletter bei meine-hp.de</html> group Die ID der Gruppe zu der ein User 4 (Diese ist über die entsprechende APIsich zum Newsletter anmelden soll Funktion abrufbar)
11.3 Optionale Parameter Mit diesen Parametern können sie zusätzliche Informationen zu ihrem Formular angeben. Sie können z.b. eine eigene Antwortadresse angeben, falls diese sich von der Absender-Email-Adresse unterscheidet. reply Antwort-Email-Adresse, an die mögliche Fragen gesendet werden können (in den Email- meine-antwort@example.org Programmen als Antwort verfassen-adresse) landingpage http://www.newsletter-anmeldung.com/ successpage http://www.newsletteranmeldung.com/erfolgreich/ failpage http://www.newsletteranmeldung.com/fehler/ dupentrypage http://www.newsletteranmeldung.com/doppelte-anmeldung/ Dieser Aufruf gibt nur einen Code zurück, der einen User zum richtigen Newsletter (Kunde und Gruppe) einträgt. 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 die selben Bezeichnungen haben, die Newsletter2Go vorschreibt. Daher ist es Ihnen dringend empfohlen, sich ein Formular über den Generator auf Newsletter2go.de erstellen zu lassen. 12. Attribut setzen 12.1 Allgemeines
Um ein Attribut für einen Empfänger über die Newsletter2Go API zu belegen, setzen Sie einen POST Request über HTTPS an folgende URL: https://www.newsletter2go.de/de/api/set/attribute/ 12.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Das keyword muss in Kleinbuchstaben übergeben werden! Ihr Newsletter2Go API-Key. Sie key finden ihn in Ihrem Account unter Die Empfänger Id zu der ein rid Attribut gesetzt werden soll. Das Attribut, welches gesetzt werden attribute soll. Der Wert, den das Attribut erhalten value soll. acbd18db4cc2f85cedef654fccc4a4d8 45 Vorname, Nachname, Alter Max, Mustermann, 28 Die Standardattribute werden mit folgenden Namen identifiziert: Vorname, Nachname, Email, Handy, Geschlecht. Anders geschriebene Attribute werden als spezifisch angesehen. 13. Newsletter abrufen 13.1 Allgemeines
Um Ihre Newsletter über die Newsletter2Go API abzurufen, setzten Sie einen POST Request über HTTPS an folgende URL: https://www.newsletter2go.de/de/api/get/newsletters/ 13.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Das keyword muss in Kleinbuchstaben übergeben werden! Ihr Newsletter2Go API-Key. Sie key finden ihn in Ihrem Account unter acbd18db4cc2f85cedef654fccc4a4d8 Diese Funktion benötigt nur den Api-Key und liefert ein Array, welches die Newsletter enthält. Diese Newsletter sind Abbildungen, die folgende Schlüssel enthalten: id, state, html und name. 14. Webversion-Link abrufen 14.1 Allgemeines
Um den Link für die Webversion für einen Newsletter über die Newsletter2Go API abzurufen, setzten Sie einen POST Request über HTTPS an folgende URL: https://www.newsletter2go.de/de/api/get/webversionlink/ 14.2 Notwendige Parameter Folgende Parameter sind notwendig, um eine Newsletter ID über die Schnittstelle zu erstellen. Das keyword muss in Kleinbuchstaben übergeben werden! Ihr Newsletter2Go API-Key. Sie key finden ihn in Ihrem Account unter Die Newsletter ID, zu der sie den id Webversion-Link haben wollen. acbd18db4cc2f85cedef654fccc4a4d8 456