Storefront API Newsletter

Newsletter-Anmeldungen und -Abmeldungen für eingeloggte Kunden und anonyme Besucher über die Storefront API als Opt-in/Opt-out abbilden.

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

​

Methoden für den Newsletter

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.

​

GET newsletter/targetGroups

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" }
  ]
}

​

POST newsletter/subscribe

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 [e-mail] 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": "[e-mail]",
  "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.

​

POST newsletter/subscribeConfirm

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.

​

POST newsletter/unsubscribe

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 [e-mail] von den Newsletter-Zielgruppen 1 und 2 abmeldet

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

​

Beispiel-Request

{
  "email": "[e-mail]",
  "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.

​

POST newsletter/unsubscribeConfirm

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.

​

POST newsletter/blacklist

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 [e-mail] auf die Sperrliste setzt

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

​

Beispiel-Request

{
  "email": "[e-mail]"
}

​

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.

​

POST newsletter/blacklistConfirm

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.