Storefront API Newsletter - WEBSALE Dokumentation

Die Newsletter API dient zur Integration von Newsletter-Anmeldungen und -Abmeldungen für das WEBSALE Newsletter-Modul in der Storefront. Sie kann sowohl für eingeloggte Kunden als auch für anonyme Besucher verwendet werden und bildet die üblichen Opt-in/Opt-out-Vorgänge im Frontend ab.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl	Endpunkte	GET	PUT	POST	DELETE
Liste der im Shop konfigurierten Newsletter-Zielgruppen	`newsletter/targetGroups`
Erstellt ein neues Newsletter-Abo.	`newsletter/subscribe`
Bestätigt ein neues Newsletter-Abo.	`newsletter/subscribeConfirm`
Abmeldung vom Newsletter.	`newsletter/unsubscribe`
Bestätigung der Abmeldung vom Newsletter.	`newsletter/unsubscribeConfirm`
Setzt eine E-Mail-Adresse auf die Sperrliste.	`newsletter/blacklist`
Bestätigt die Sperre der E-Mail-Adresse.	`newsletter/blacklistConfirm`

Mithilfe dieser Methoden wird das komplette Newsletter-Management im Shop gesteuert: Sie lesen die konfigurierten Zielgruppen aus und ermöglichen das Anlegen, Bestätigen (Double-Opt-In) und Beenden von Newsletter-Abos – optional je Zielgruppe. Zusätzlich können E-Mail-Adressen dauerhaft über eine Blacklist vom Versand ausgeschlossen werden, was ebenfalls per Bestätigungslink abgesichert ist. Validierungen und typische Fehlerfälle (z. B. fehlende Pflichtfelder, ungültige Zielgruppen oder falsche bzw. abgelaufene Opt-in-Tokens) werden dabei über definierte Fehlercodes zurückgemeldet. Der folgende Aufruf liefert alle im Shop konfigurierten Newsletter-Zielgruppen. Er kann verwendet werden, um beim Newsletter-Anmeldeformular oder auf Profil-/Einstellungsseiten auswählbare Zielgruppen anzuzeigen.

GET https://<ihr-shop>.de/api/v1/newsletter/targetGroups

Parameterübersicht

Parameter	Typ	Beschreibung
—	—	Keine zusätzlichen Parameter.

Beispiel-Response

{
  "items": [
    { "deactivated": false, "id": 1, "name": "foo" },
    { "deactivated": false, "id": 2, "name": "asdf" }
  ]
}

Mit folgendem Aufruf wird für eine E-Mail-Adresse ein Newsletter-Abo angelegt und optional Zielgruppen zugeordnet. Bei aktiviertem Double-Opt-In-Verfahren wird zuerst eine Bestätigungs-E-Mail verschickt. Das Abonnement ist erst nach Bestätigung aktiv. Es ist für Anmeldeformulare mit Auswahl von Zielgruppen und Erfassung zusätzlicher Felder verwendbar. Beispiel-Aufruf, der ein Newsletter-Abo für das Kundenkonto mit der E-Mail-Adresse maria.musterfrau@example.com und die Newslettergruppen 1 und 2 anlegt. Als optionale Zusatzinformationen wird der Vor- und Nachname mitgegeben

POST https://<ihr-shop>.de/api/v1/newsletter/subscribe

Beispiel-Request

{
  "email": "maria.musterfrau@example.com",
  "targetGroupIds": [1, 2],
  "fields": {
    "firstName": "Maria",
    "lastName": "Musterfrau"
  }
}

Parameterübersicht

Parameter	Typ	Beschreibung
`email`	string	Pflichtfeld E-Mail-Adresse, die den Newsletter abonnieren soll.
`targetGroupIds`	array (number)	Liste von Zielgruppen, die dieses Abo erhalten soll. Die gültigen IDs erhält man über `GET newsletter/targetGroups`.
`fields`	object	Objekt mit zusätzlichen Angaben zum Abonnenten. Die Schlüssel und Formate müssen den in `newsletter.fields` konfigurierten Feldern entsprechen.

Fehlercodes

Code	Beschreibung
`missingField`	Ein als Pflichtfeld markiertes Feld fehlt.
`invalidField`	Ein Wert entspricht nicht den Validierungsregeln in der Konfiguration. Mehr dazu: https://websale.atlassian.net/wiki/x/EQAZzg
`invalidTargetGroupId`	Eine angegebene Zielgruppen-ID existiert nicht.
`deactivatedTargetGroup`	Eine angegebene Zielgruppe ist deaktiviert oder nimmt keine neuen Abonnenten auf.

Mit dem folgenden Aufruf kann ein zuvor über „Newsletter/Subscribe” gestartetes Newsletter-Abo per Opt-In-Token bestätigt werden. Dadurch wird das Abo für die angegebene E-Mail-Adresse aktiviert. Er ist für das Handling in der Double-Opt-In-E-Mail verwendbar. Beispiel-Aufruf, der mithilfe des Bestätigungscodes aus der E-Mail das Newsletter-Abo bestätigt

POST https://<ihr-shop>.de/api/v1/newsletter/subscribeConfirm

Beispiel-Request

{
  "otok": "<Code aus der Mail>"
}

Parameterübersicht

Parameter	Typ	Beschreibung
`otok`	string	Pflichtfeld Opt-In-Token aus der Bestätigungs-E-Mail.

Fehlercodes

Code	Beschreibung
`actionNotAllowed`	Der Opt-In-Token ist für diese Aktion ungültig oder abgelaufen.
`internalError`	Interner Fehler; kann nur von WEBSALE behoben werden.

Mit folgendem Aufruf kann man sich vom Newsletter abmelden – auf Wunsch auch nur aus bestimmten Zielgruppen. Bei aktiviertem Double-Opt-In-Verfahren ist unter Umständen eine zusätzliche Bestätigungs-E-Mail erforderlich. Dies ist beispielsweise für ein Abmeldeformular oder einen Abmelde-Link nutzbar. Beispiel-Aufruf, der das Kundenkonto mit der E-Mail maria.musterfrau@example.com von den Newsletter-Zielgruppen 1 und 2 abmeldet

POST https://<ihr-shop>.de/api/v1/newsletter/unsubscribe

Beispiel-Request

{
  "email": "maria.musterfrau@example.com",
  "targetGroupIds": [1, 2]
}

Parameterübersicht

Parameter	Typ	Beschreibung
`email`	string	Pflichtfeld E-Mail-Adresse, die abgemeldet werden soll.
`targetGroupIds`	array (int)	Liste der Zielgruppen-IDs, aus denen abgemeldet werden soll.

Fehlercodes

Code	Beschreibung
`missingField`	Ein als Pflichtfeld markiertes Feld fehlt.
`invalidField`	Ein Wert entspricht nicht den Validierungsregeln in der Konfiguration. Mehr dazu: https://websale.atlassian.net/wiki/x/EQAZzg
`invalidTargetGroupId`	Eine angegebene Zielgruppen-ID existiert nicht.
`deactivatedTargetGroup`	Eine angegebene Zielgruppe ist deaktiviert oder nimmt keine neuen Abonnenten auf.

Mit dem folgenden Aufruf kann eine per Opt-In-Token aus der Bestätigungs-E-Mail erfolgte Newsletter-Abmeldung bestätigt und endgültig abgeschlossen werden. Er ist für das Handling der Abmelde-E-Mail verwendbar. Beispiel-Aufruf, der mithilfe des Bestätigungscodes aus der E-Mail das Newsletter-Abo beendet

POST https://<ihr-shop>.de/api/v1/newsletter/unsubscribeConfirm

Beispiel-Request

{
  "otok": "<Code aus der Mail>"
}

Parameterübersicht

Parameter	Typ	Beschreibung
otok	string	Pflichtfeld Opt-In-Token aus der Bestätigungs-E-Mail.

Fehlercodes

Code	Beschreibung
`actionNotAllowed`	Der Opt-In-Token ist für diese Aktion ungültig oder abgelaufen.
`internalError`	Interner Fehler; kann nur von WEBSALE behoben werden.

Mit dem folgenden Aufruf wird eine E-Mail-Adresse auf die Sperrliste gesetzt, sodass an diese Adresse keine Newsletter mehr versendet werden. Die Sperre kann durch erneutes Abonnieren wieder aufgehoben werden. Dies ist beispielsweise für Opt-Out-Funktionen wie „Keine Newsletter mehr erhalten“ verwendbar. Beispiel-Aufruf, der die E-Mail-Adresse maria.musterfrau@websale.de auf die Sperrliste setzt

POST https://<ihr-shop>.de/api/v1/newsletter/blacklist

Beispiel-Request

{
  "email": "maria.musterfrau@websale.de"
}

Parameterübersicht

Parameter	Typ	Beschreibung
`email`	string	Pflichtfeld Die zu sperrende E-Mail-Adresse.

Fehlercodes

Code	Beschreibung
`emailCheckFailed`	Die angegebene E-Mail-Adresse ist ungültig.

Folgender Aufruf bestätigt die zuvor angeforderte Sperre (auf die Sperrliste setzen) einer E-Mail-Adresse per Opt-In-Token aus der Bestätigungs-Mail. Verwendbar für den Abschluss des Sperrlisten-Prozesses nach Klick auf den Link aus der E-Mail. Beispiel-Aufruf, der mithilfe des Bestätigungscodes aus der E-Mail die E-Mail-Adresse auf die Sperrliste setzt

POST https://<ihr-shop>.de/api/v1/newsletter/blacklistConfirm

Beispiel-Request

{
  "otok": "<Code aus der Mail>"
}

Parameterübersicht

Parameter	Typ	Beschreibung
otok	string	Pflichtfeld Opt-In-Token aus der Bestätigungs-E-Mail.

Fehlercodes

Code	Beschreibung
`actionNotAllowed`	Der Opt-In-Token ist für diese Aktion ungültig oder abgelaufen.

​Unterstützte Methoden

​Methoden für den Newsletter

​GET newsletter/targetGroups

​Parameterübersicht

​Beispiel-Response

​POST newsletter/subscribe

​Beispiel-Request

​Parameterübersicht

​Fehlercodes

​POST newsletter/subscribeConfirm

​Beispiel-Request

​Parameterübersicht

​Fehlercodes

​POST newsletter/unsubscribe

​Beispiel-Request

​Parameterübersicht

​Fehlercodes

​POST newsletter/unsubscribeConfirm

​Beispiel-Request

​Parameterübersicht

​Fehlercodes

​POST newsletter/blacklist

​Beispiel-Request

​Parameterübersicht

​Fehlercodes

​POST newsletter/blacklistConfirm

​Beispiel-Request

​Parameterübersicht

​Fehlercodes

Unterstützte Methoden

Methoden für den Newsletter

GET newsletter/targetGroups

Parameterübersicht

Beispiel-Response

POST newsletter/subscribe

Beispiel-Request

Parameterübersicht

Fehlercodes

POST newsletter/subscribeConfirm

Beispiel-Request

Parameterübersicht

Fehlercodes

POST newsletter/unsubscribe

Beispiel-Request

Parameterübersicht

Fehlercodes

POST newsletter/unsubscribeConfirm

Beispiel-Request

Parameterübersicht

Fehlercodes

POST newsletter/blacklist

Beispiel-Request

Parameterübersicht

Fehlercodes

POST newsletter/blacklistConfirm

Beispiel-Request

Parameterübersicht

Fehlercodes