Storefront API Newsletter

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.