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.

Inhaltsverzeichnis

1 1. Unterstützte Methoden
2 2. Datenfelder für Zielgruppen und Abonnenten
- 2.1 2.1 Datenfelder einer Zielgruppe
- 2.2 2.2 Datenfelder eines Abonnenten
3 3. Methoden für Zielgruppen
4 4. Methoden für Abonnenten
5 5. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Zielgruppen	newsletter/group
Abonnenten	newsletter/subscriber

2. 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:

2.1 Datenfelder einer Zielgruppe

Name	Typ	Verwendung

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"
}

2.2 Datenfelder eines Abonnenten

Name	Typ	Verwendung

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
    ]
}

3. 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.

3.1 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:

deactivated, createdAt

Fehlercodes:

Fehler	Typ	Grund

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] `sort` ∉ {"asc", "desc"} `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 ":".

3.2 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:

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

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"	`id` ist ungültig.
404 Not Found		Zielgruppe mit `id`=`{id}` wurde nicht gefunden.

3.3 POST newsletter/group

Eine neue Newsletter-Zielgruppe wird erstellt. Es muss ein Name angegeben werden, alle anderen Parameter werden ignoriert. 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

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.

3.4 PUT newsletter/group/{id}

Diese Methode aktualisiert den Namen einer bestehenden Zielgruppe anhand ihrer ID. Andere Parameter im Request-Body werden ignoriert.

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

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	"invalidFormat”	Der Parameter `name` ist kein String.
400 Bad Request	"invalidValue"	`id` ist ungültig.
404 Not Found		Zielgruppe mit `id`=`{id}` wurde nicht gefunden.

3.5 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.

Schreibberechtigungen für Newsletter-Daten sind erforderlich.

Beispiel:

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

Antwort:

Die Zielgruppe wird erfolgreich deaktiviert. Es wird keine Antwort im Body gesendet.

{}

Fehlercodes:

Fehler	Typ	Grund

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	"invalidValue"	`id` ist ungültig.
404 Not Found		Newsletter mit `id`=`{id}` wurde nicht gefunden.

4. Methoden für Abonnenten

4.1 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, updatedAt

Sortierfelder:

id, createdAt

Fehlercodes:

Fehler	Typ	Grund

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] \| `sort` ∉ {"asc", "desc"} \| `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 ":".

4.2 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:

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

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"	`id` ist ungültig.
404 Not Found		Abonnent mit `id`=`{id}` wurde nicht gefunden.

4.3 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,
  "changes": [],
  "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

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, `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”	Eines der im Shop konfigurierten verpflichtenden Newsletterfelder ist nicht gesetzt.

4.4 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. Andere Parameter im Request Body werden ignoriert.

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

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.
400 Bad Request	"invalidValue"	`id` ist ungültig.
400 Bad Request	"invalidFormat"	`email` ist kein String, `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”	Eines der im Shop konfigurierten verpflichtenden Newsletterfelder ist nicht gesetzt.
404 Not found

API-Referenz Newsletter

Inhaltsverzeichnis

1. Unterstützte Methoden

2. Datenfelder für Zielgruppen und Abonnenten

2.1 Datenfelder einer Zielgruppe

Beispiel:

2.2 Datenfelder eines Abonnenten

Beispiel:

3. Methoden für Zielgruppen

3.1 GET newsletter/group

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 GET newsletter/group/{id}

Beispiel:

Antwort:

Fehlercodes:

3.3 POST newsletter/group

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.4 PUT newsletter/group/{id}

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.5 DELETE newsletter/group/{id}

Beispiel:

Antwort:

Fehlercodes:

4. Methoden für Abonnenten

4.1 GET newsletter/subscriber

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

4.2 GET newsletter/subscriber/{id}

Beispiel:

Antwort:

Fehlercodes:

4.3 POST newsletter/subscriber/

Beispiel:

Request Body:

Antwort:

Fehlercodes:

4.4 PUT newsletter/subscriber/{id}

Beispiel:

Request Body:

Antwort:

Fehlercodes: