Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt

Use this file to discover all available pages before exploring further.

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.
BefehlEndpunkteGETPUTPOSTDELETE
Liste der im Shop konfigurierten Newsletter-Zielgruppennewsletter/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

ParameterTypBeschreibung
——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 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

ParameterTypBeschreibung
emailstringPflichtfeld
E-Mail-Adresse, die den Newsletter abonnieren soll.
targetGroupIdsarray (number)Liste von Zielgruppen, die dieses Abo erhalten soll. Die gültigen IDs erhält man über GET newsletter/targetGroups.
fieldsobjectObjekt mit zusätzlichen Angaben zum Abonnenten. Die Schlüssel und Formate müssen den in newsletter.fields konfigurierten Feldern entsprechen.

​
Fehlercodes

CodeBeschreibung
missingFieldEin als Pflichtfeld markiertes Feld fehlt.
invalidFieldEin Wert entspricht nicht den Validierungsregeln in der Konfiguration. Mehr dazu: https://websale.atlassian.net/wiki/x/EQAZzg
invalidTargetGroupIdEine angegebene Zielgruppen-ID existiert nicht.
deactivatedTargetGroupEine 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

ParameterTypBeschreibung
otokstringPflichtfeld
Opt-In-Token aus der Bestätigungs-E-Mail.

​
Fehlercodes

CodeBeschreibung
actionNotAllowedDer Opt-In-Token ist für diese Aktion ungültig oder abgelaufen.
internalErrorInterner 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 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

ParameterTypBeschreibung
emailstringPflichtfeld
E-Mail-Adresse, die abgemeldet werden soll.
targetGroupIdsarray (int)Liste der Zielgruppen-IDs, aus denen abgemeldet werden soll.

​
Fehlercodes

CodeBeschreibung
missingFieldEin als Pflichtfeld markiertes Feld fehlt.
invalidFieldEin Wert entspricht nicht den Validierungsregeln in der Konfiguration. Mehr dazu: https://websale.atlassian.net/wiki/x/EQAZzg
invalidTargetGroupIdEine angegebene Zielgruppen-ID existiert nicht.
deactivatedTargetGroupEine 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

ParameterTypBeschreibung
otokstringPflichtfeld
Opt-In-Token aus der Bestätigungs-E-Mail.

​
Fehlercodes

CodeBeschreibung
actionNotAllowedDer Opt-In-Token ist für diese Aktion ungültig oder abgelaufen.
internalErrorInterner 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 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

ParameterTypBeschreibung
emailstringPflichtfeld
Die zu sperrende E-Mail-Adresse.

​
Fehlercodes

CodeBeschreibung
emailCheckFailedDie 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

ParameterTypBeschreibung
otokstringPflichtfeld
Opt-In-Token aus der Bestätigungs-E-Mail.

​
Fehlercodes

CodeBeschreibung
actionNotAllowedDer Opt-In-Token ist für diese Aktion ungültig oder abgelaufen.