Newsletter2Go - API Dokumentation Changelog

Transcrição

Version 1.1 vom 24.10.2011, Feedback an [email protected]
Newsletter2Go - API Dokumentation
Changelog:
(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
1.
2.
3.
4.
5.
6.
7.
Allgemeines
Rückgabewerte
Statuscodes
Versenden einer Email
Versenden einer SMS
Erstellen eines Newsletters
Statistiken abrufen
8. Empfänger erstellen
1. Allgemeines
 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:
key
value-type
success int
value
String or
null
status
int
reason String
valuedescription
example
0 or 1
1 means success, 0 means fail
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
200
code explanations see status codes.
'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 HTTPStatuscodes.























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'
500 => 'Internal Server Error'
4. Versenden einer Email
1. Allgemeines
2. Notwendige Parameter
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:
https://www.newsletter2go.de/de/api/send/email/
ab.
4.2 Notwendige Parameter
Sämtliche Parameter müssen url-encoded übergeben werden.
Folgende Parameter sind notwendig, um eine Email über die Schnittstelle
zu versenden.
Die Reihenfolge der Parameter ist beliebig.
Die Parameter sind case-sensitive.
Das keyword muss in Kleinbuchstaben übergeben werden.
Parameter Beschreibung
Ihr Newsletter2Go API-Key. Sie
key
finden ihn in Ihrem Account unter
"Konto".
to
Die Empfänger-Emailadresse
from
Die Absender-Email-Adresse
subject
Der Betreff der Email
html
Der komplette HTML-Quellcode
text
Der Text-Part der Email
Die Kategorie der Email. Es stehen
basic und plus zur Auswahl
category
Beispielwert
acbd1ddb4cc2f85cedasd54fccc4a4d8
[email protected]
[email protected]
Ihre Bestellung vom 23.05.2011
<html><body>Hallo
Freunde,<br/>...</body></html>
Hallo Freunde, …
basic
4.3 Optionale Parameter
Die id des Newsletters bei
id
Newsletter2Go. Sie wird benötigt, falls
Sie die Reporting-Funktionen von
Beispielwert
Default-Wert
1453
null
Newsletter2Go über die API nutzen
möchten.
Mit 1 Einschalten des Debug-Modus. Ist
der Debug-Modus eingeschaltet, können
debug
Sie die API von Newsletter2go testen,
1
ohne dass die Email tatsächlich versendet
wird.
Eine eigene Referenz, die Sie beliebig
ref
Januar2011
wählen können.
Versenden der Email 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
date
1306351118
UNIX-Timestamp übergeben, wird die
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 ReplyAdresse angeben. Das ist die Emailreply
Adresse, an die eine Email geschickt
[email protected]
wird, wenn der Empfänger auf
"antworten" klickt.
An- bzw. Abschalten des Linktrackings.
Standardmäßig ist diese Option
eingschaltet. Wird das Linktracking
linktracking
false
abgeschaltet, werden Links nicht
umgeschrieben und damit können Klicks
auf Links nicht registriert werden.
An- bzw. Abschalten des ÖffnungsTracking.
Standardmäßig ist diese Option
opentracking
0
eingeschaltet. Wird das Opentracking
abgeschaltet, werden Öffnungen der
Emails nicht registriert.
0
null
Die aktuelle Zeit
der Einlieferung
der Email
Die fromAdresse.
1
1
5. Versenden einer SMS
1. Allgemeines
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/
Folgende Parameter sind notwendig, um eine SMS über die Schnittstelle
zu versenden.
Das keyword muss in Kleinbuchstaben übergeben werden!
Beispielwert
Ihr Newsletter2Go API-Key. Sie finden ihn
key
acbd18db4cc2f85csdef654fccc4a4d8
in Ihrem Account unter "Konto".
to
Die Empfänger-Mobilfunknummer
+49 178 1234567890
Der Text der Nachricht. Maximal sind 1530
message
Lieber Peter, ich freue mich, dass ...
Zeichen möglich.
Die Kategorie der SMS. Es stehen basic und
category
basic
plus zur Auswahl
Dies ist die Absenderkennung der SMS. Nur
relevant, falls category = plus. Die
from
Absenderkennung darf maximal 11
alphanumerische oder 16 numerische Zeichen
enthalten. Hinweis: Verzichten Sie auf
Beispielwert Default-Wert
Meine Firma
id
debug
ref
date
Sonderzeichen jeglicher Art, da sie nicht auf jedem
Mobilfunkgerät uneingeschränkt dargestellt
werden.
Die id des Newsletters bei Newsletter2Go. Sie wird
benötigt, falls Sie die Reporting-Funktionen von 1453
Newsletter2Go über die API nutzen möchten.
Mit 1 Einschalten des Debug-Modus. Ist der
Debug-Modus eingeschaltet, können Sie die API
1
von Newsletter2go testen, ohne dass die SMS
tatsächlich versendet wird.
Eine eigene Referenz, die Sie beliebig wählen
SMSkönnen.
Angebot
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 1306351118
UNIX-Timestamp übergeben, wird die SMS nicht
entgegengenommen und Fehlercode 420 wird
returned.
null
0
null
Die aktuelle Zeit
der Einlieferung
der SMS.
6. Erstellen eines Newsletters
1. Allgemeines
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.
Folgende Parameter sind notwendig, um eine Newsletter ID über die
Schnittstelle zu erstellen.
key
"Konto".
Name des Newsletters (nicht der
name
Betreff)
Der Typ des Newsletters. Es stehen
type
sms und email zur Auswahl
Die Kategorie der SMS. Es stehen
category
basic und plus zur Auswahl
Beispielwert
acbd18db4cc2f85cedef654fccc4a4d8
Newsletter 2011 Nr. 1
sms
basic
Im zurückgegebenen JSON – Objekt wird in dem value Feld die erzeugte
Newsletter_ID zurückgeliefert.
7. Statistiken abrufen
1. Allgemeines
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 JSONObjekt, 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.
Folgende Parameter sind notwendig, um die Statistiken eines Newsletters
abzurufen.
key
"Konto".
Id
Die Newsletter-ID
Beispielwert
acbd18db4cc2f85cedasd54fccc4a4d8
3
Es sind nur Newsletter-Ids erlaubt, die zu Ihrem Account gehören.
Hier können Sie wählen, welche Statistik-Werte Sie abrufen wollen. Geben
sie keine dieser Parameter an, dann werden standardmäßig alle StatistikWerte 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.
Parameter
recipients
uniqueOpenRate
openRate
notOpenRate
uniqueClickRate
clickRate
notClickRate
bounceRate
deliveryRate
Beschreibung
Anzahl der Empfänger für den
Newsletter
eindeutige Öffnungsrate
Öffnungsrate (enthält
mehrfache Öffnungen)
Verhältnis Nicht-Öffnungen
zur Gesamt-Empfängerzahl
eindeutige Klickrate
Klickrate (enthält mehrfache
Klicks)
Verhältnis von Empfängern die
nicht geklickt haben zur
Gesamt-Empfängerzahl
Bounces im Verhältnis zur
Gesamt-Empfängerzahl
Gesamt-Empfängerzahl Bounces (Differenz)
Beispielwert
0
1
true
false
FALSE
TRUE
1
1
0
Für SMS-Newsletter ist nur der recipients-Parameter möglich.
8. Empfänger erstellen
1. Allgemeines
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/
key
"Konto".
email
Email-Adresse des Empfängers
mobile
Handynummer des Empfängers
Beispielwert
acbd18db4cc2as5cedef654fccc4a4d8
[email protected]
0123456789
Es ist mindestens ein Parameter von email und mobile nötig. Es können
aber auch beide Parameter angegeben werden.
Beispielwert
lastname
firstname
Nachname des Empfängers
Vorname des Empfängers
Geschlecht des Empfängers (m oder
gender
f)
Gruppenzugehörigkeit des
group1
Empfängers
group2
Weitere Gruppenzugehörigkeiten
Haarfarbe Spezifische / Eigene Attribute
Schuhgroes
Weitere Attribute
se
Mustermann
Max
m
Informatiker
Fußballer
weiß
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“: „[email protected]“,
„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.

Newsletter2Go - API Dokumentation Changelog

Transcrição

Documentos relacionados

Online Marketing – English (m/f)

API Dokumentation

API Dokumentation v 3.3

mobilant Email2SMS API - Spezifikationen Inhaltsverzeichnis

Soundkarte ultron PCI 7.1 Kanal Octosound retail Artikel

Software zum Jahreswechsel:Angebotsblatt.qxd.qxd

Seite als pdf speichern

(API) und Import - bei der German QP Association

Pressemitteilung als PDF

leserreise antarktis