> ## 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. # API-Referenz Newsletter > Newsletter-Zielgruppen und Abonnentenlisten über die Admin Interface API auflisten, neu anlegen, aktualisieren sowie gezielt wieder entfernen. 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 ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/group ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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/\{id} 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/group/2 ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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. | ### 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/group ``` #### Request Body ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "name": "Exklusive Angebote" } ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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. | ### PUT newsletter/group/\{id} 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/group/2 ``` #### Request Body ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "name": "newName" } ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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. | ### DELETE newsletter/group/\{id} 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/group/2 ``` #### Antwort Die Zielgruppe wird erfolgreich deaktiviert. ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "success": true } ``` #### Fehlercodes | **Fehler** | **Typ** | **Grund** | | ---------------- | ------- | ------------------------------------------------------------------------------ | | 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet. | | 403 Forbidden | | Sie 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 ### 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/subscriber ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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. | ### GET newsletter/subscriber/\{id} 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/subscriber/1 ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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. | ### 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/subscriber/ ``` #### Request Body ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "email": "m.mustermann@websale.de", "fields": { "firstName": "Max", "lastName": "Mustermann" }, "targetGroupIds": [ 1, 2 ] } ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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. | ### PUT newsletter/subscriber/\{id} 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/newsletter/subscriber/1 ``` #### Request Body ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "fields": { "firstName": "Max", "lastName": "Mustermann" }, "targetGroupIds": [ 1, 2, 3 ] } ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | | 403 Forbidden | | Sie 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](https://websale.atlassian.net/servicedesk/customer/portal/6) Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.