API Dokumentation v1.7 Newsletter2Go 29. Dezember 2012

i

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

Changelog 1.6 → 1.7 • Parameter category ist bei Emails nicht mehr notwendig.

1.5 → 1.6 • Funktion Credits abfragen hinzugef¨ ugt

1.4 → 1.5 • Funktion Empf¨ anger abmelden hinzugef¨ ugt

1.3 → 1.4 • Funktion Newsletter senden hinzugef¨ ugt • Funktion Empf¨ anger setzen(Newsletter) hinzugef¨ ugt • Funktion Attribut erstellen hinzugef¨ ugt • Funktion Newsletter erstellen ge¨ andert (optionale Paramter hinzugef¨ ugt) • neue Statuscodes hinzugef¨ ugt

1.2 → 1.3 • Funktion Attribut setzen hinzugef¨ ugt • Funktion Newsletter abrufenhinzugef¨ ugt • Funktion Webversion-Link abrufen hinzugef¨ ugt • neue Statuscodes hinzugef¨ ugt

1.1 → 1.2 • Funktion Gruppen abrufen hinzugef¨ ugt • Funktion Spezifische Merkmale abrufenhinzugef¨ ugt • Funktion Formular key generieren hinzugef¨ ugt • neue Statuscodes hinzugef¨ ugt

1.0 → 1.1 • Zwei neue Optionale Parameter (opentracking, linktracking) in der Email versenden Funktion

0.9 → 1.0 • category ist neuer notwendiger Parameter beim Versenden einer Email • Funktion Newsletter erstellen hinzugef¨ ugt • Funktion Statistiken abrufen erstellen hinzugef¨ ugt • Funktion Empf¨ anger erstellen erstellen hinzugef¨ ugt • neue Statuscodes hinzugef¨ ugt

ii

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

Inhalt 1 Allgemeines

1

2 R¨ uckgabewerte

2

3 Statuscodes

3

4 Versenden einzelner Emails / SMS 4.1 Versenden einer Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 Versenden einer SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4 4 5

5 Newsletter-Management 5.1 Newsletter erstellen . . . . . . . . . . . 5.2 Empf¨ anger zum Newsletter hinzuf¨ ugen 5.3 Newsletter senden . . . . . . . . . . . 5.4 Statistiken abrufen . . . . . . . . . . . 5.5 Newsletter abrufen . . . . . . . . . . . 5.6 Webversion-Link abrufen . . . . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

7 7 7 8 8 9 10

6 Empf¨ anger-Management 6.1 Empf¨ anger erstellen 6.2 Attribut erstellen . . 6.3 Attribut setzen . . . 6.4 Spezifische Merkmale 6.5 Gruppen abrufen . . 6.6 Empf¨ anger abmelden

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

11 11 12 12 12 13 13

7 Account Management 7.1 Abrufen der verf¨ ugbaren Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

14 14

. . . . . . . . . . . . . . . abrufen . . . . . . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

. . . . . .

iii

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

1 Allgemeines • Mit der Newsletter2Go API k¨ onnen Sie die wesentlichen Funktionalit¨aten von Newsletter2Go in Ihre Anwendung integrieren. • Die API orientiert sich am REST-Protokoll. • S¨amtliche HTTP-Aufrufe m¨ ussen per POST durchgef¨ uhrt werden. • Die R¨ uckgabewerte erfolgen stets im JSON-Format. • Bei jeder HTTP-Anfrage m¨ ussen alle POST- n url-encoded u ¨bergeben werden, um eine korrekte ¨ Ubertragung und Verarbeitung gew¨ ahrleisten zu k¨onnen. • S¨amtliche API-Anfragen m¨ ussen u ¨ber das SSL-Protokoll (HTTPS) laufen. Anfragen ohne SSL sind nicht m¨ oglich.

Parameter • S¨amtliche Parameter m¨ ussen url-encoded u ¨bergeben werden. • Die Reihenfolge der Parameter ist beliebig. • Die Parameter sind case-sensitive. • Das keyword muss in Kleinbuchstaben u ¨bergeben werden.

1

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

2 R¨ uckgabewerte S¨ amtliche R¨ uckgabewerte der Newsletter2go API erfolgen im JSON Format (application/json) Es wird immer genau ein JSON-Objekt zur¨ uckgegeben, welches immer genau vier key-value-Paare besitzt: key success value

value-type int String oder null

value-example 0 or 1

status

int

200

reason

String

’OK’

description 1 means success, o 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 code explanations see section Statuscodes. A textual representation of the status code

Ein Beispiel f¨ ur ein resultierendes JSON-Objekt w¨are: { success :0 , value : null , status :405 , r e a s o n : ” Method Not Allowed , POST R e q u i e r e d ” }

2

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

3 Statuscodes Die zur¨ uckgegebenen 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’ 442 ’not possible to send newsletter’ 443 ’newsletter must be draft to add a recipient’ 444 ’attribute already exists’ 500 ’Internal Server Error’

3

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

4 Versenden einzelner Emails / SMS Mit den folgenden Funktionen k¨ onnen sie einzelne Emails bzw SMS versenden. Dies ist n¨ utzlich um z.B. Transaktionsmails zu verschicken oder wenn Sie Newsletter-Emails u ¨ber eine Schleife versenden wollen.

4.1 Versenden einer Email Um u ¨ber die Newsletter2Go API eine E-Mail versenden zu k¨onnen, setzen Sie aus Ihrer Anwendung einen POST Request via HTTPS Protokoll an folgende URL: https://www.newsletter2go.de/de/api/send/email/ ab. Notwendige Parameter Parameter key

to from subject html

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Empf¨ anger-Emailadresse Die Absender-Email-Adresse Der Betreff der Email Der komplette HTML-Quellcode

text

Der Text-Part der Email

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8

[email protected] [email protected] Ihre Bestellung vom 23.05.2011 Hallo Freunde,
... Hallo Freunde, ...

Optionale Parameter Parameter id

debug

ref

Beschreibung Die id des Newsletters bei Newsletter2Go. Sie wird ben¨ otigt, falls Sie die Reporting-Funktionen von Newsletter2Go u ¨ber die API nutzen m¨ ochten. Mit 1 Einschalten des Debug-Modus. Ist der Debug-Modus eingeschaltet, k¨ onnen Sie die API von Newsletter2go testen, ohne dass die Email tats¨ achlich versendet wird. Eine eigene Referenz, die Sie beliebig w¨ ahlen k¨ onnen.

Beispielwert 1453

Default-Wert null

1

0

Januar2011

null

4

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

date

reply

linktracking

opentracking

Versenden der Email zeitversetzt. Es muss ein UNIXTimestamp u ¨bergeben werden. Liegt der Timestamp in der Vergangenheit, ist er negativ oder leer wird sofort versendet. Wird kein valider UNIX-Timestamp u ¨bergeben, wird die Email nicht entgegengenommen und Fehlercode 420 wird zur¨ uck gegeben. Der Timestamp darf maximal 1 Jahr in der Zukunft liegen. Sie k¨ onnen eine alternative Reply-Adresse angeben. Das ist die Email-Adresse, an die eine Email geschickt wird, wenn der Empf¨ anger auf ¨ antworten”klickt. Anbzw. Abschalten des Linktrackings. Standardm¨ aßig ist diese Option eingschaltet. Wird das Linktracking abgeschaltet, werden Links nicht umgeschrieben und damit k¨ onnen Klicks auf Links nicht registriert werden. An- bzw. Abschalten des ¨ Offnungs-Tracking. Standardm¨ aßig ist diese Option eingeschaltet. Wird das Opentracking abgeschal¨ tet, werden Offnungen der Emails nicht registriert.

1306351118

Die aktuelle Zeit der Einlieferung der Email

[email protected]

Die from-Adresse.

false

1

0

1

4.2 Versenden einer SMS Um u ¨ber die Newsletter2Go API eine SMS versenden zu k¨onnen, setzen Sie aus Ihrer Anwendung einfach einen POST Request via HTTPS Protokoll an folgende URL: https://www.newsletter2go.de/de/api/send/sms/

5

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected] Notwendige Parameter Parameter key to from message category

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Empf¨ anger-Mobilfunknummer Die Absender-Kennung, nur notwendig, falls category = plus Der Text der Nachricht. Maximal sind 1530 Zeichen m¨ oglich. Die Kategorie der SMS. Es stehen basic und plus zur Auswahl

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 00491781234567890 Ihr Name Lieber Peter, ich freue mich, dass ... basic

Optionale Parameter Parameter from

id

ref date

debug

Beschreibung 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 Sonderzeichen jeglicher Art, da sie nicht auf jedem Mobilfunkger¨ at uneingeschr¨ ankt dargestellt werden. Die id des Newsletters bei Newsletter2Go. Sie wird ben¨ otigt, falls Sie die ReportingFunktionen von Newsletter2Go u ochten. ¨ber die API nutzen m¨ Eine eigene Referenz, die Sie beliebig w¨ ahlen k¨ onnen. Versenden der SMS zeitversetzt. Es muss ein UNIX-Timestamp u ¨bergeben werden. Liegt der Timestamp in der Vergangenheit, ist er negativ oder leer wird sofort versendet. Wird kein valider UNIX-Timestamp u ¨bergeben, wird die SMS nicht entgegengenommen und Fehlercode 420 wird returned. Mit 1 Einschalten des DebugModus. Ist der Debug-Modus eingeschaltet, k¨ onnen Sie die API von Newsletter2go testen, ohne dass die SMS tats¨ achlich versendet wird.

Beispielwert Meine Firma

Default-Wert

1453

null

SMS-Angebot

null

1306351118

Die aktuelle Zeit der Einlieferung der SMS.

1

0

6

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

5 Newsletter-Management Dieser Abschnitt beschreibt Funktionen, mit denen Sie ihre Newsletter bearbeiten k¨onnen. Sie k¨onnen Newsletter erstellen, Empf¨ anger zu diesen hinzuf¨ ugen und den Newsletter dann abschicken. Desweiteren k¨onnen Sie sich die IDs aller Newsletter holen und dar¨ uber Statistiken abrufen.

5.1 Newsletter erstellen Hier erstellen Sie ein Newsletter-Objekt, dem sp¨ater Inhalte und Empf¨anger zugewiesen werden k¨onnen und der anschließend abgesendet werden kann. Um einen Newsletter u ¨ber die Newsletter2Go API zu erstellen, setzen Sie einen POST Request u ¨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¨ uckzuliefern. Notwendige Parameter Parameter key name type category

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Name des Newsletters (nicht der Betreff) Der Typ des Newsletters. Es stehen sms und email zur Auswahl Die Kategorie der SMS. Es stehen basic und plus zur Auswahl. Nur notwendig wenn type == sms.

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 Newsletter 2011 Nr.1 sms basic

Im zur¨ uckgegebenen JSON-Objekt wird in dem value Feld die erzeugte Newsletter ID zur¨ uckgeliefert. Optionale Parameter Parameter subject html text sms from reply

Beschreibung Betreff des Newsletters Der komplette HTMLQuellcode Der Text-Part des Newsletters Der Inhalt f¨ ur einen SMS Newsletter Die Absender-Email-Adresse des Newsletters Die Antwort-Email-Adresse des Newsletters

Beispielwert Newsletter Nr. 11 Hallo Freunde,
... Hallo Freunde, ... Hallo Freunde, ...

Default-Wert null null

[email protected]

null

[email protected]

null

null null

5.2 Empf¨ anger zum Newsletter hinzuf¨ ugen Um einen Empf¨ anger zu einem Newsletter u ugen, setzen Sie einen ¨ber die Newsletter2Go API hinzuzuf¨ POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/set/recipient/

7

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected] Notwendige Parameter Parameter key id email mobile

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Newsletter ID, zu der Sie einen Empf¨anger hinzuf¨ ugen wollen. Die Email-Adresse des Empf¨angers Die Mobilfunknummer des Empf¨angers

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 456 [email protected] 123456789

Der Empf¨anger wird entweder u ¨ber das Attribut email oder das Attribut mobile identifiziert. Nur eines von beiden ist obligatorisch. Es m¨ ussen nicht beide Attribute angegeben werden.

5.3 Newsletter senden Um einen Newsletter u ¨ber die Newsletter2Go API abzusenden, setztn Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/send/newsletter/ Notwendige Parameter Parameter key id

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Newsletter ID, von dem zu sendenden Newsletter

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 456

Optionale Parameter Parameter date

Beschreibung Versenden des Newsletters zeitversetzt. Es muss ein UNIXTimestamp u ¨bergeben werden. Liegt der Timestamp in der Vergangenheit, ist er negativ oder leer wird sofort versendet. Wird kein valider UNIX-Timestamp u ¨bergeben, wird die Email nicht entgegengenommen und Fehlercode 420 wird zur¨ uck gegeben. Der Timestamp darf maximal 1 Jahr in der Zukunft liegen.

Beispielwert 1306351118

Default-Wert Die aktuelle Zeit

Mit dieser Funktion ¨ andern Sie den Status des Newsletters auf Senden. Dadurch wird der Newsletter versendet. Es k¨ onnen nur Newsletter versendet werden, deren aktueller Status Entwurf bzw. draft oder api ist. Ein Newsletter darf nur gesendet werden, wenn er mindestens einen Empf¨anger aufweist.

5.4 Statistiken abrufen Um f¨ ur einen Newsletter Statistiken abzurufen, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/get/statistics/

8

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected] Das Antwort-JSON-Objekt enth¨ alt in dem value-Feld ein zweites JSON-Objekt, welches die StatistikWerte enth¨alt. Da es sich um Verh¨ altnis-zahlen handelt, liegen sie zwischen 0 und 1 (z.B. 0.3 entspricht dann 30%). Es ist aber auch denkbar, dass ein Wert gr¨ oßer als 1 zur¨ uckgegeben wird (z.B. 2 entspricht dann 200%) Die Bezeichnungen der Statistikwerte entsprechen den optionalen Parametern. Notwendige Parameter Parameter key id

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Newsletter-ID

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 3

Es sind nur Newsletter-Ids erlaubt, die zu Ihrem Account geh¨oren. Optionale Parameter Hier k¨onnen Sie w¨ ahlen, welche Statistik-Werte Sie abrufen wollen. Geben sie keine dieser Parameter an, dann werden standardm¨ aßig alle Statistik-Werte zur¨ uckgegeben. Die Auswahl der Statistik erfolgt u ¨ber einen boolschen Wert (0,1,true,false), wobei 1 und true bedeuten, dass der Wert zur¨ uckgegeben werden soll und 0 bzw. false bedeuten, dass er nicht zur¨ uckgeliefert wird. Parameter recipients uniqueOpenRate openRate notOpenRate uniqueClickRate clickRate notClickRate bounceRate deliveryRate

Beschreibung Anzahl der Empf¨ anger f¨ ur den Newsletter ¨ eindeutige Offungsrate ¨ ¨ Offnungsrate (enth¨ alt mehrfache Offnungen) ¨ Verh¨ altnis Nicht-Offnungen zur Gesamt-Empf¨angerzahl eindeutige Klickrate Klickrate (enth¨ alt mehrfache Klicks) Verh¨ altnis von Empf¨anger die nicht geklickt haben zur GesamtEmpf¨ angerzahl Bounces im Verh¨ altnis zur Gesamt-Empf¨angerzahl Gesamt-Empf¨ angerzahl - Bounces (Differenz)

Beispielwert 0 1 true false FALSE TRUE 1 1 0

F¨ ur SMS-Newsletter ist nur der recipients-Parameter m¨oglich.

5.5 Newsletter abrufen Um Ihre Newsletter u ¨ber die Newsletter2Go API abzurufen, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/get/newsletters/ Notwendige Parameter Parameter key

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”.

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8

Diese Funktion ben¨ otigt nur den Api-Key und liefert ein Array, welches die Newsletter enth¨alt. Diese Newsletter sind Abbildungen, die folgende Schl¨ ussel enthalten: id, state, html und name.

9

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

5.6 Webversion-Link abrufen Um den Link f¨ ur die Webversion f¨ ur einen Newsletter u ¨ber die Newsletter2Go API abzurufen, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/get/webversionlink/ Notwendige Parameter Parameter key id

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Newsletter ID, von dem zu sendenden Newsletter

10

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 456

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

6 Empf¨ anger-Management Funktionen die hier als Empf¨ anger-Management bezeichnet sind, geben Ihnen die M¨oglichkeit ihre Empf¨anger zu verwalten. Empf¨ anger und Empf¨angerattribute (Merkmale) k¨onnen erstellt werden. Zus¨atzlich ist es m¨ oglich sich Attribute und Gruppen ausgeben zu lassen.

6.1 Empf¨ anger erstellen Sie k¨onnen mit dieser Funktion Ihrem Newsletter2Go-Adressbuch neue Empf¨anger hinzuf¨ ugen. Dies ist sinnvoll, wenn Sie z.B. automatisiert Ihr Shopsystem mit Ihrem Newsletter2Go-Adressbuch synchronisieren wollen. Wichtig: um einzelne (Transaktions-)Emails bzw. (Transaktions-)SMS u ¨ber diese API zu versenden, ist es nicht notwendig Empf¨ anger vorher anzulegen. Um einen Empf¨ anger zu erstellen bzw. zu ihrem Adressbuch hinzuzuf¨ ugen, setzen Sie einen Post Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/create/recipient/ Notwendige Parameter Parameter key email mobile

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Email-Adresse des Empf¨ angers Handynummer des Empf¨angers

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 [email protected] 0123456789

Es ist nur ein Parameter von email und mobile obligatorisch. Es k¨onnen aber auch beide Parameter angegeben werden. Optionale Parameter Parameter lastname firstname gender group1 group2 Haarfarbe Schuhgroesse

Beschreibung Nachname des Empf¨ angers Vorname des Empf¨ angers Geschlecht des Empf¨ angers (m oder f) Gruppenzugeh¨ origkeit des Empf¨angers Weiter Gruppenzugeh¨ origkeiten Spezifische / Eigene Attribute weiteres Attribut

Beispielwert Mustermann Max m NewsletterLeser W¨ahler Schwarz 43

Es k¨onnen beliebig viele Gruppen und Attribute angegeben werden. Die Schl¨ ussel f¨ ur Gruppen m¨ ussen mit group beginnen. Diese Schl¨ ussel m¨ ussen durchnummeriert werden. Ein Attribut-Name darf nicht das Wort group enthalten. Attributnamen d¨ urfen keine Umlaute oder Sonderzeichen enthalten. Beispiel-JSON: { ” key ” : a c b d 1 8 d b 4 c c 2 a s d c e d e f 6 5 4 f c c c 4 a 4 d 8 , ” e m a i l ” : ” test@example . o r g ” , ” f i r s t n a m e ” : ”Max” , ” group1 ” : Mustermaurer , ” group2 ” : ” Musterhandwerker ” , ” H a a r f a r b e ” : ” Schwarz ” , ” Bewertung ” : 4 } Sind Attribute (z.B. Haarfarbe) nicht vorhanden, so werden sie neu angelegt. Dasselbe gilt f¨ ur Gruppen.

11

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

6.2 Attribut erstellen Um ein spezifisches Attribut u ¨ber die Newsletter2Go API zu erstellen, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/create/attribute/ Notwendige Parameter Parameter key name

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Der Name des zu erstellenden Attributes

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 Haarfarbe

Das Attribut darf nur Zeichen von a-z , A-Z und 0-9 enthalten. Andere Zeichen werden entfernt.

6.3 Attribut setzen Um ein Attribut f¨ ur einen Empf¨ anger u ¨ber die Newsletter2Go API zu belegen, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/set/attribute/ Notwendige Parameter Parameter key email mobile attribute value

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Email-Adresse des Empf¨angers zu dem ein Attribut gesetzt werden soll Die Empf¨ anger-Mobilfunknummer zu der ein Attribut gesetzt werden soll Das Attribut, welches gesetzt werden soll. Der Wert, den das Attribut erhalten soll

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 [email protected] 0123456789 Vorname, Nachname, Alter Max, Mustermann, 28

Die Standardattribute werden mit folgenden Bezeichnern angesprochen: firstname, lastname, mail, mobile, gender. Anders benannte Attribute werden als spezifische Attribute angesehen. Der Empf¨anger wird entweder u ¨ber das Attribut email oder das Attribut mobile identifiziert. Nur eines von beiden ist obligatorisch. Es m¨ ussen nicht beide Attribute angegeben werden.

6.4 Spezifische Merkmale abrufen Um Ihre Attribute u ¨ber die Newsletter2Go API abzurufen, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/get/attributes/ Notwendige Parameter Parameter key

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”.

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8

Diese Funktion ben¨ otigt nur den Api-Key und liefert die Attribut Identifier und die dazugeh¨ origen Namen.

12

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

6.5 Gruppen abrufen Um Ihre Gruppen u ¨ber die Newsletter2Go API abzurufen, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/get/groups/ Notwendige Parameter Parameter key

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”.

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8

Diese Funktion ben¨ otigt nur den Api-Key und liefert die Gruppen Identifier (ID) und die dazugeh¨ origen Namen.

6.6 Empf¨ anger abmelden Um einen Empf¨ anger als abgemeldet zu markieren, damit er nicht mehr angeschrieben werden kann, setzen Sie einen POST Request u ¨ber HTTPS an folgende URL: https://www.newsletter2go.de/de/api/set/unsubscribed/ Notwendige Parameter Parameter key email mobile

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”. Die Email-Adresse des Empf¨angers Die Mobilfunknummer des Empf¨angers

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8 [email protected] 0049179123456789

Der Empf¨anger wird entweder u ¨ber das Attribut email oder das Attribut mobile identifiziert. Nur eines von beiden ist obligatorisch. Es m¨ ussen nicht beide Attribute angegeben werden.

13

Version 1.7 vom 29. Dezember 2012, Feedback an [email protected]

7 Account Management 7.1 Abrufen der verf¨ ugbaren Credits Sie k¨onnen Ihren aktuellen Credit-Stand abrufen, indem Sie aus Ihrer Anwendung einen POST Request via HTTPS Protokoll an folgende URL absetzen: https://www.newsletter2go.de/de/api/get/credits/ Notwendige Parameter Parameter key

Beschreibung Ihr Newsletter2Go API-Key. Sie finden ihn in Ihrem Account unter “Einstellungen”.

Beispielwert acbd1ddb4cc2f85cedasd54fccc4a4d8

Im zur¨ uckgegebenen JSON-Objekt enth¨ alt der value-Wert die verf¨ ugbaren Credits. Unterschieden wird zwischen “freemailcount”(1000 Email-Credits kostenlos jeden Monat), “emailcount”(PrepaidEmail-Credits), “abocount”(Abo-Email-Credits), und “smscount”(SMS-Credits). Eine m¨ogliche Antwort w¨are: { ’ success ’ : 1 , ’ value ’ : { ’ freemailcount ’ : 985 , ’ emailcount ’ : 158820 , ’ abocount ’ : 0 , ’ smscount ’ : 173 }, ’ status ’ : 200 , ’ r e a s o n ’ : ’OK’ }

14