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

{
    "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": "[e-mail]",
    "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 hinzugefügt 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

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

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

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

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

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

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": "[e-mail]",
            "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

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": "[e-mail]",
    "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

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

​

Request Body

{
    "email": "[e-mail]",
    "fields": {
        "firstName": "Max",
        "lastName": "Mustermann"
    },
    "targetGroupIds": [
        1,
        2
    ]
}

​

Antwort

{
    "blacklisted": false,
    "createdAt": "2025-02-05T10:23:34.000Z",
    "createdBy": 1,
    "email": "[e-mail]",
    "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		Die Double-Opt-In-E-Mail konnte nicht versendet werden. Der Abonnent wurde nicht angelegt.

​

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 (beispielsweise Vorname, Nachname) und targetGroupIds (Zielgruppen-Zugehörigkeit) verändert werden. Unbekannte Parameter im Request Body führen zu einem Fehler.

​

Änderung der E-Mail-Adresse

Die E-Mail-Adresse ist im Shop eindeutig. Gehört die neue Adresse bereits einem anderen Abonnenten, wird die Anfrage mit 409 Conflict und dem Typ "emailAlreadyExists" abgelehnt. Eine Änderung, die nur die Groß- und Kleinschreibung betrifft, gilt nicht als Änderung der E-Mail-Adresse.

Wenn die E-Mail-Adresse geändert wird, muss der Inhaber der neuen Adresse die Änderung per Double-Opt-In bestätigen. Dazu versendet der Shop die Double-Opt-In-E-Mail aus newsletter.newsletter → doubleOptInEmailSubscribe an die neue Adresse. Der Token enthält die ID des Abonnenten. Nach der Bestätigung mit NewsletterSubscribeConfirm wird die neue Adresse auf diesen Abonnenten übertragen. Es entsteht kein zusätzlicher Abonnent und es wird keine Willkommens-E-Mail versendet.

Bis zur Bestätigung gilt Folgendes:

• Die gespeicherte E-Mail-Adresse bleibt unverändert.
• Alle anderen Änderungen aus dem Request Body, also fields und targetGroupIds, werden sofort gespeichert und erscheinen in changes.
• Die Antwort enthält zusätzlich das Feld pendingEmail mit der neuen, noch nicht bestätigten Adresse.

Kann die Double-Opt-In-E-Mail nicht versendet werden, antwortet die Schnittstelle mit 503 Service Unavailable. In diesem Fall wird nichts gespeichert.

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

Wird zusätzlich email mit einer neuen Adresse übergeben, enthält die Antwort weiterhin die bisherige Adresse in email und die neue Adresse in pendingEmail:

{
    "email": "[e-mail]",
    "pendingEmail": "[e-mail]",
    ...
}

​

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": "[e-mail]",
    "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}.
409 Conflict	”emailAlreadyExists”	Die neue E-Mail-Adresse gehört bereits einem anderen Abonnenten.
500 Internal Server Error	”internalError”	Der Abonnent konnte nicht geladen werden. Die Prüfung, ob die neue E-Mail-Adresse bereits vergeben ist, ist fehlgeschlagen. Die E-Mail-Adresse konnte ohne Double-Opt-In nicht direkt geändert werden.
503 Service Unavailable		Die Double-Opt-In-E-Mail an die neue E-Mail-Adresse konnte nicht versendet werden. Es wurde nichts gespeichert.

​

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.