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.

Der Endpunkt newsletter/ stellt Ihnen eine Schnittstelle zur Verfügung mit der Sie Newsletter-Abonnenten und Newsletter-Zielgruppen verwalten können. Darüber können Sie Zielgruppen erstellen, aktualisieren und löschen. Es ist ebenfalls möglich, eine Liste mit allen Newsletter-Abonnenten abzurufen und neue Abonnenten anzulegen.

​
Unterstützte Methoden

Angabe aller unterstützten Methoden.
Befehl/InfoEndpunkteGETPOSTPUTDELETE
Zielgruppennewsletter/group
Abonnentennewsletter/subscriber

​
Datenfelder für Zielgruppen und Abonnenten

Die Newsletter-Verwaltung unterscheidet zwei zentrale Entitäten: Zielgruppen und Abonnenten. Zielgruppen dienen der thematischen oder organisatorischen Einteilung von Abonnenten, etwa für gezielte Kampagnen oder regionale Segmente. Abonnenten sind einzelne Nutzer, die sich für einen Newsletter registriert haben und optional in mehreren Zielgruppen gleichzeitig geführt werden können. Die folgenden Tabellen beschreiben die jeweiligen Datenfelder:

​
Datenfelder einer Zielgruppe

NameTypVerwendung
idIntegerEindeutiger Index der Zielgruppe
nameStringName der Zielgruppe
deactivatedBooleanIst auf false gesetzt, wenn Abonnenten dieser Gruppe beitreten können. 1 = deaktiviert und 0 = aktiv.
createdAtStringErstellungszeitpunkt (ISO 8601, UTC)
updatedAtStringZeitpunkt der letzten Aktualisierung (ISO 8601-Format, UTC)

​
Beispiel

{
    "createdAt": "2024-11-08T15:00:33.000Z",
    "deactivated": false,
    "id": 2,
    "name": "Zielgruppe 2",
    "updatedAt": "2025-01-21T15:08:55.000Z"
}

​
Datenfelder eines Abonnenten

NameTypVerwendung
blacklistedBooleanGibt an, ob die E-Mail-Adresse auf einer Blacklist steht
createdAtStringErstellungszeitpunkt (ISO 8601, UTC)
createdByIntegerID des Nutzers, der den Eintrag erstellt hat
emailStringE-Mail-Adresse des Abonnenten
fieldsObjektJSON-Objekt mit zusätzlichen Registrierungsdaten wie Vorname, Nachname, Anrede
idIntegerEindeutiger Index des Abonnenten
isImportBooleanGibt an, ob der Datensatz importiert wurde.
subshopIdStringID des Subshops, über den die Anmeldung erfolgte
targetGroupIdsArrayListe der Zielgruppen-IDs, denen der Abonnent zugeordnet ist

​
Beispiel

{
    "blacklisted": false,
    "createdAt": "2025-04-28T13:13:16.000Z",
    "createdBy": 0,
    "email": "m.mustermann@websale.de",
    "fields": {
        "firstName": "Max",
        "lastName": "Mustermann",
        "salutation": "1"
    },
    "id": 1,
    "isImport": true,
    "subshopId": "deutsch",
    "targetGroupIds": [
        1
    ]
}

​
Methoden für Zielgruppen

Die folgenden Methoden ermöglichen das Verwalten von Newsletter-Zielgruppen. Zielgruppen dienen der Segmentierung von Abonnenten innerhalb des Shopsystems. Über die API lassen sich bestehende Zielgruppen abrufen, bearbeiten, erstellen oder deaktivieren. Neue Abonnenten können nur aktiven Zielgruppen zugewiesen werden – eine Deaktivierung bedeutet, dass keine neuen Einträge mehr aufgenommen werden können.

​
GET newsletter/group

Mit dieser Methode wird eine Liste aller im System vorhandenen Zielgruppen geliefert. Optional kann die Ergebnisliste durch Filter auf den Status deactivated oder das Erstellungsdatum eingeschränkt werden. Eine Sortierung nach diesen Feldern ist ebenfalls möglich. Berechtigungen zum Lesen von Newsletter-Daten sind erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/group

​
Antwort

{
    "endReached": true,
    "items": [
        {
            "id": 1,
            "deactivated": false,
            "name": "Zielgruppe 1",
            "createdAt": "2024-11-07T11:04:35.000Z",
            "updatedAt": "2025-01-21T15:08:55.000Z"
        },
        {
            "id": 2,
            "name": "Zielgruppe 2",
            "deactivated": false,
            "createdAt": "2024-11-08T15:00:33.000Z",
            "updatedAt": "2025-01-21T15:08:55.000Z"
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}

​
Filterfelder

deactivated, createdAt

​
Sortierfelder

createdAt, updatedAt, name, id, deactivated

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Newslettern.
400 Bad Request”invalidValue”
400 Bad Request”invalidCharacters”size ist keine Ganzzahl.
Ein Filterwert ist ungültig.
400 Bad Request”unknownDataField”Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request”unknownOperation”Ein Filtertyp ist ungültig.
400 Bad Request”syntaxError”sort enthält mehr als einen oder keinen ”:”.

​
GET newsletter/group/

Diese Methode lädt die Details einer bestimmten Zielgruppe anhand ihrer ID. Zurückgegeben werden Informationen wie Name, Status, Erstellungs- und Aktualisierungsdatum. Berechtigungen zum Lesen von Newsletter-Daten sind erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/group/2

​
Antwort

{
    "createdAt": "2024-11-08T15:00:33.000Z",
    "deactivated": false,
    "id": 2,
    "name": "Zielgruppe 2",
    "updatedAt": "2025-01-21T15:08:55.000Z"
}

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Newslettern.
400 Bad Requestid ist ungültig.
404 Not FoundZielgruppe mit id={id} wurde nicht gefunden.

​
POST newsletter/group

Eine neue Newsletter-Zielgruppe wird erstellt. Es muss ein Name angegeben werden, unbekannte Parameter führen zu einem Fehler. Nach erfolgreichem Erstellen wird der vollständige Eintrag mit Zeitstempeln und ID zurückgegeben. Erstellberechtigungen für Newsletter-Daten sind erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/group

​
Request Body

{
    "name": "Exklusive Angebote"
}

​
Antwort

{
    "id": 3,
    "name": "Exklusive Angebote",
    "deactivated": false,
    "createdAt": "2025-05-01T12:00:00.000Z",
    "updatedAt": "2025-05-01T12:00:00.000Z"
}

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Newslettern.
400 Bad RequestRequest body konnte nicht geladen werden.
400 Bad Request”invalidFormat”name ist kein String.
400 Bad Request”missing”name wurde nicht übergeben.
400 Bad Request”unknownDataField”Es wird versucht, ein unbekanntes Feld zu übergeben. Nur name ist erlaubt.
400 Bad Request”duplicateEntry”Eine Zielgruppe mit diesem name existiert bereits.

​
PUT newsletter/group/

Diese Methode aktualisiert den Namen einer bestehenden Zielgruppe anhand ihrer ID. Unbekannte Parameter im Request-Body führen zu einem Fehler. Schreibberechtigungen für Newsletter-Daten sind erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/group/2

​
Request Body

{
    "name": "newName"
}

​
Antwort

{
    "id": 2,
    "name": "newName",
    "deactivated": false,
    "createdAt": "2024-11-08T15:00:33.000Z",
    "updatedAt": "2025-01-21T15:08:55.000Z"
}

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Newslettern.
400 Bad RequestRequest body konnte nicht geladen werden.
id ist ungültig.
400 Bad Request”invalidFormat”Der Parameter name ist kein String.
400 Bad Request”missing”name wurde nicht übergeben.
400 Bad Request”unknownDataField”Es wird versucht, ein unbekanntes Feld zu übergeben. Nur name ist erlaubt.
404 Not FoundZielgruppe mit id={id} wurde nicht gefunden.

​
DELETE newsletter/group/

Eine Zielgruppe wird deaktiviert. Ab dem Zeitpunkt der Deaktivierung können keine neuen Abonnenten mehr dieser Gruppe beitreten. Bereits zugewiesene Abonnenten bleiben jedoch erhalten. Löschberechtigungen für Newsletter-Daten sind erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/group/2

​
Antwort

Die Zielgruppe wird erfolgreich deaktiviert. 
{
    "success": true
}

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Newslettern.
400 Bad Requestid ist ungültig.
404 Not FoundDie Zielgruppe mit id={id} wurde nicht gefunden.

​
Methoden für Abonnenten

​
GET newsletter/subscriber

Diese Methode liefert eine paginierte Liste aller Newsletter-Abonnenten im System. Die Abonnentendaten umfassen unter anderem die verschlüsselte E-Mail-Adresse, das Anmeldedatum sowie die persönlichen Informationen im Feld fields. Über Filter- und Sortierparameter lassen sich die Ergebnisse gezielt einschränken. Zum Zugriff sind entsprechende Leserechte für Newsletterdaten erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/subscriber

​
Antwort

{
    "endReached": true,
    "items": [
        {
            "blacklisted": false,
            "createdAt": "2025-02-05T10:23:34.000Z",
            "createdBy": 1,
            "email": "m.mustermann@websale.de",
            "fields": {
                "firstName": "Max",
                "lastName": "Mustermann"
            },
            "id": 43,
            "isImport": false,
            "subshopId": "",
            "targetGroupIds": [
                1,
                2
            ]
        }
    ],
    "nextPageToken": "NA",
    "totalCount": 1
}

​
Filterfelder

targetGroupIds, createdAt

​
Sortierfelder

id, createdAt

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Newslettern.
400 Bad Request”invalidValue”size ∉ [1;300]pageToken ist keine Zahl oder kleiner als 0.
400 Bad Request”invalidCharacters”size ist keine Ganzzahl.
Ein Filterwert ist ungültig.
400 Bad Request”unknownDataField”Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request”unknownOperation”Ein Filtertyp ist ungültig.
400 Bad Request”syntaxError”sort enthält mehr als einen oder keinen ”:“.
503 Service UnavailableInterner Fehler beim Laden der Abonnentendaten.

​
GET newsletter/subscriber/

Diese Methode lädt die vollständigen Daten eines einzelnen Newsletter-Abonnenten anhand seiner ID. Zusätzlich enthält die Antwort eine Historie aller Änderungen am Datensatz im Abschnitt changes, sofern diese vorhanden sind. Für die Nutzung dieser Methode sind entsprechende Leserechte für Newsletterdaten erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/subscriber/1

​
Antwort

{
    "blacklisted": false,
    "changes": [
        {
            "changes": {
                "fields.lastName": {
                    "new": "Mustermann",
                    "old": "Musterfrau"
                }
            },
            "createdAt": "2025-02-05T10:28:48.000Z",
            "entryId": 43,
            "id": 12,
            "isImport": true,
            "userId": 1
        }
    ],
    "createdAt": "2025-02-05T10:23:34.000Z",
    "createdBy": 1,
    "email": "m.mustermann@websale.de",
    "fields": {
        "firstName": "Max",
        "lastName": "Mustermann"
    },
    "id": 43,
    "isImport": false,
    "subshopId": "",
    "targetGroupIds": [
        1,
        2
    ]
}

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Newslettern.
400 Bad Requestid ist ungültig.
404 Not FoundAbonnent mit id={id} wurde nicht gefunden.
503 Service UnavailableInterner Fehler beim Laden des Abonnenten.

​
POST newsletter/subscriber/

Ein neuer Newsletter-Abonnent wird erstellt. Standardmäßig muss der Abonnent die Anmeldung bestätigen (Double-Opt-In). Da eine Bestätigung erforderlich ist, erscheint der Abonnent erst nach erfolgtem Opt-In in der Abonnentenliste. Für die Nutzung dieser Methode sind entsprechende Erstellrechte für Newsletterdaten erforderlich

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/subscriber/

​
Request Body

{
    "email": "m.mustermann@websale.de",
    "fields": {
        "firstName": "Max",
        "lastName": "Mustermann"
    },
    "targetGroupIds": [
        1,
        2
    ]
}

​
Antwort

{
    "blacklisted": false,
    "createdAt": "2025-02-05T10:23:34.000Z",
    "createdBy": 1,
    "email": "m.mustermann@websale.de",
    "fields": {
        "firstName": "Max",
        "lastName": "Mustermann"
    },
    "id": 44,
    "isImport": false,
    "subshopId": "",
    "targetGroupIds": [
        1,
        2
    ]
}

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Newslettern.
400 Bad RequestRequest body konnte nicht geladen werden.
400 Bad Request”invalidFormat”email ist kein String oder hat kein gültiges E-Mail-Format, fields ist kein Objekt, targetGroupIds ist kein Array von Zahlen oder eines der Newsletterfelder hat gemäß den im Shop konfigurierten Überprüfungen einen ungültigen Wert.
400 Bad Request”missing”email, fields oder targetGroupIds wurde nicht übergeben, targetGroupIds ist ein leeres Array, oder eines der im Shop konfigurierten verpflichtenden Newsletterfelder ist nicht gesetzt.
400 Bad Request”invalidValue”email ist ein leerer String.
400 Bad Request”unknownDataField”Es wird versucht, ein unbekanntes Feld zu übergeben. Erlaubt sind nur email, fields und targetGroupIds.
503 Service UnavailableDer Double-Opt-In-Dienst ist nicht erreichbar.

​
PUT newsletter/subscriber/

Diese Methode aktualisiert die Daten eines bestehenden Newsletter-Abonnenten anhand seiner ID. Dabei können ausschließlich die Felder email, fields (z. B. Vorname, Nachname) und targetGroupIds (Zielgruppen-Zugehörigkeit) verändert werden. Unbekannte Parameter im Request Body führen zu einem Fehler. Wenn die E-Mail-Adresse geändert wird, muss der Inhaber die Anmeldung erneut bestätigen. Solange es nicht geschehen ist, bleibt die Adresse unverändert. Für die Nutzung dieser Methode sind entsprechende Schreibrechte für Newsletterdaten erforderlich.

​
Beispiel

https://www.<ihr-shop>.de/admin/api/v1/newsletter/subscriber/1

​
Request Body

{
    "fields": {
        "firstName": "Max",
        "lastName": "Mustermann"
    },
    "targetGroupIds": [
        1,
        2,
        3
    ]
}

​
Antwort

{
    "blacklisted": false,
    "changes": [
        {
            "changes": {
                "fields.firstName": {
                    "new": "Max",
                    "old": "Erika"
                },
                "fields.lastName": {
                    "new": "Mustermann",
                    "old": "Musterfrau"
                },
                "targetGroupIds": {
                    "new": [
                        1,
                        2,
                        3
                    ],
                    "old": [
                        1
                    ]
                }
            },
            "createdAt": "2025-05-08T08:18:39.000Z",
            "entryId": 1,
            "id": 1,
            "isImport": false,
            "userId": 1
        }
    ],
    "createdAt": "2025-02-05T10:23:34.000Z",
    "createdBy": 1,
    "email": "m.mustermann@websale.de",
    "fields": {
        "firstName": "Max",
        "lastName": "Mustermann"
    },
    "id": 1,
    "isImport": false,
    "subshopId": "",
    "targetGroupIds": [
        1,
        2,
        3
    ]
}

​
Fehlercodes

FehlerTypGrund
401 UnauthorizedNicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Newslettern.
400 Bad RequestRequest body konnte nicht geladen werden.
id ist ungültig.
400 Bad Request”invalidFormat”email ist kein String oder hat kein gültiges E-Mail-Format, fields ist kein Objekt, targetGroupIds ist kein Array von Zahlen oder eines der Newsletterfelder hat gemäß den im Shop konfigurierten Überprüfungen einen ungültigen Wert.
400 Bad Request”missing”targetGroupIds ist ein leeres Array, oder eines der im Shop konfigurierten verpflichtenden Newsletterfelder ist nicht gesetzt.
400 Bad Request”invalidValue”email ist ein leerer String.
400 Bad Request”unknownDataField”Es wird versucht, ein unbekanntes Feld zu übergeben. Erlaubt sind nur email, fields und targetGroupIds.
404 Not foundEs existiert kein Abonnent mit id={id}
503 Service UnavailableInterner Fehler beim Laden des Abonnenten.
Der Double-Opt-In-Dienst ist nicht erreichbar (nur bei Änderung der E-Mail-Adresse).

​
Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.