API-Referenz Newsletter - WEBSALE Dokumentation

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/Info	Endpunkte	GET	POST	PUT	DELETE
Zielgruppen	newsletter/group
Abonnenten	newsletter/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

Name	Typ	Verwendung
id	Integer	Eindeutiger Index der Zielgruppe
name	String	Name der Zielgruppe
deactivated	Boolean	Ist auf `false` gesetzt, wenn Abonnenten dieser Gruppe beitreten können. 1 = deaktiviert und 0 = aktiv.
createdAt	String	Erstellungszeitpunkt (ISO 8601, UTC)
updatedAt	String	Zeitpunkt 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

Name	Typ	Verwendung
blacklisted	Boolean	Gibt an, ob die E-Mail-Adresse auf einer Blacklist steht
createdAt	String	Erstellungszeitpunkt (ISO 8601, UTC)
createdBy	Integer	ID des Nutzers, der den Eintrag erstellt hat
email	String	E-Mail-Adresse des Abonnenten
fields	Objekt	JSON-Objekt mit zusätzlichen Registrierungsdaten wie Vorname, Nachname, Anrede
id	Integer	Eindeutiger Index des Abonnenten
isImport	Boolean	Gibt an, ob der Datensatz importiert wurde.
subshopId	String	ID des Subshops, über den die Anmeldung erfolgte
targetGroupIds	Array	Liste 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. 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

Fehler	Typ	Grund
401 Unauthorized		Nicht 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 ”:”.

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

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Newslettern.
400 Bad Request		`id` ist ungültig.
404 Not Found		Zielgruppe mit `id`=`{id}` wurde nicht gefunden.

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

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Newslettern.
400 Bad Request		Request 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.

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

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Newslettern.
400 Bad Request		Request 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 Found		Zielgruppe mit `id`=`{id}` wurde nicht gefunden.

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

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Newslettern.
400 Bad Request		`id` ist ungültig.
404 Not Found		Die Zielgruppe mit `id`=`{id}` wurde nicht gefunden.

Methoden für Abonnenten

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

Fehler	Typ	Grund
401 Unauthorized		Nicht 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 Unavailable		Interner Fehler beim Laden der Abonnentendaten.

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

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Newslettern.
400 Bad Request		`id` ist ungültig.
404 Not Found		Abonnent mit `id`=`{id}` wurde nicht gefunden.
503 Service Unavailable		Interner Fehler beim Laden des Abonnenten.

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

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Newslettern.
400 Bad Request		Request 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 Unavailable		Der Double-Opt-In-Dienst ist nicht erreichbar.

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

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Newslettern.
400 Bad Request		Request 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 found		Es existiert kein Abonnent mit `id={id}`
503 Service Unavailable		Interner 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.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Documentation Index

​Unterstützte Methoden

​Datenfelder für Zielgruppen und Abonnenten

​Datenfelder einer Zielgruppe

​Beispiel

​Datenfelder eines Abonnenten

​Beispiel

​Methoden für Zielgruppen

​GET newsletter/group

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET newsletter/group/

​Beispiel

​Antwort

​Fehlercodes

​POST newsletter/group

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT newsletter/group/

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE newsletter/group/

​Beispiel

​Antwort

​Fehlercodes

​Methoden für Abonnenten

​GET newsletter/subscriber

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET newsletter/subscriber/

​Beispiel

​Antwort

​Fehlercodes

​POST newsletter/subscriber/

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT newsletter/subscriber/

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Datenfelder für Zielgruppen und Abonnenten

Datenfelder einer Zielgruppe

Beispiel

Datenfelder eines Abonnenten

Beispiel

Methoden für Zielgruppen

GET newsletter/group

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET newsletter/group/

Beispiel

Antwort

Fehlercodes

POST newsletter/group

Beispiel

Request Body

Antwort

Fehlercodes

PUT newsletter/group/

Beispiel

Request Body

Antwort

Fehlercodes

DELETE newsletter/group/

Beispiel

Antwort

Fehlercodes

Methoden für Abonnenten

GET newsletter/subscriber

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET newsletter/subscriber/

Beispiel

Antwort

Fehlercodes

POST newsletter/subscriber/

Beispiel

Request Body

Antwort

Fehlercodes

PUT newsletter/subscriber/

Beispiel

Request Body

Antwort

Fehlercodes

Support