API reference newsletter - WEBSALE Dokumentation

The newsletter/ endpoint provides an interface for managing newsletter subscribers and newsletter target groups. You can create, update and delete target groups. You can also retrieve a list of all newsletter subscribers and create new subscribers.

Supported methods

List of all supported methods.

Command/Info	Endpoints	GET	POST	PUT	DELETE
Target groups	newsletter/group
Subscribers	newsletter/subscriber

Data fields for target groups and subscribers

Newsletter management distinguishes two central entities: target groups and subscribers. Target groups are used for thematic or organizational classification of subscribers, for example for targeted campaigns or regional segments. Subscribers are individual users who have registered for a newsletter and optionally can be listed in several target groups at the same time. The following tables describe the respective data fields:

Data fields of a target group

Name	Type	Usage
id	Integer	Unique index of the target group
name	String	Name of the target group
deactivated	Boolean	Set to `false` if subscribers can join this group. 1 = deactivated and 0 = active.
createdAt	String	Time of creation (ISO 8601, UTC)
updatedAt	String	Time of the last update (ISO 8601 format, UTC)

Example

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

Data fields of a subscriber

Name	Type	Usage
blacklisted	Boolean	Indicates whether the email address is on a blacklist.
createdAt	String	Time of creation (ISO 8601, UTC)
createdBy	Integer	ID of the user who created the entry.
email	String	Email address of the subscriber.
fields	Object	JSON object with additional registration data such as first name, last name, salutation.
id	Integer	Unique index of the subscriber.
isImport	Boolean	Indicates whether the record was imported.
subshopId	String	ID of the subshop through which the registration was made.
targetGroupIds	Array	List of target group IDs the subscriber is assigned to.

Example

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

Methods for target groups

The following methods let you manage newsletter target groups. Target groups are used to segment subscribers within the shop system. Via the API you can retrieve, edit, create or deactivate existing target groups. New subscribers can only be assigned to active target groups. Deactivation means that no new entries can be added. This method returns a list of all target groups existing in the system. Optionally, the result list can be limited by filters on the deactivated status or the creation date. Sorting by these fields is also possible. Permissions to read newsletter data are required.

Example

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

Response

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

Filter fields

deactivated, createdAt

Sort fields

createdAt, updatedAt, name, id, deactivated

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read newsletters.
400 Bad Request	”invalidValue”
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

This method loads the details of a specific target group by its ID. Information such as name, status, time of creation and time of update is returned. Permissions to read newsletter data are required.

Example

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read newsletters.
400 Bad Request		`id` is invalid.
404 Not Found		Target group with `id`=`{id}` was not found.

Creates a new newsletter target group. A name must be provided; unknown parameters lead to an error. After successful creation, the full entry with timestamps and ID is returned. Create permissions for newsletter data are required.

Example

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

Request body

{
    "name": "Exklusive Angebote"
}

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create newsletters.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`name` is not a string.
400 Bad Request	”missing”	`name` was not provided.
400 Bad Request	”unknownDataField”	An attempt is being made to pass an unknown field. Only `name` is allowed.
400 Bad Request	”duplicateEntry”	A target group with this `name` already exists.

This method updates the name of an existing target group by its ID. Unknown parameters in the request body lead to an error. Write permissions for newsletter data are required.

Example

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

Request body

{
    "name": "newName"
}

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write newsletters.
400 Bad Request		Request body could not be loaded. `id` is invalid.
400 Bad Request	”invalidFormat”	The `name` parameter is not a string.
400 Bad Request	”missing”	`name` was not provided.
400 Bad Request	”unknownDataField”	An attempt is being made to pass an unknown field. Only `name` is allowed.
404 Not Found		Target group with `id`=`{id}` was not found.

A target group is deactivated. From the time of deactivation, no new subscribers can join this group. Already assigned subscribers remain. Delete permissions for newsletter data are required.

Example

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

Response

The target group is deactivated successfully.

{
    "success": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete newsletters.
400 Bad Request		`id` is invalid.
404 Not Found		The target group with `id`=`{id}` was not found.

Methods for subscribers

This method returns a paginated list of all newsletter subscribers in the system. The subscriber data includes, among other things, the encrypted email address, the registration date and personal information in the fields field. The results can be specifically limited via filter and sort parameters. For access, the corresponding read permissions for newsletter data are required.

Example

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

Response

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

Filter fields

targetGroupIds, createdAt

Sort fields

id, createdAt

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read newsletters.
400 Bad Request	”invalidValue”	`size` ∉ [1;300] `pageToken` is not a number or is less than 0.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
503 Service Unavailable		Internal error while loading subscriber data.

This method loads the full data of a single newsletter subscriber by their ID. The response additionally contains a history of all changes to the record in the changes section, if any are available. To use this method, the corresponding read permissions for newsletter data are required.

Example

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read newsletters.
400 Bad Request		`id` is invalid.
404 Not Found		Subscriber with `id`=`{id}` was not found.
503 Service Unavailable		Internal error while loading the subscriber.

A new newsletter subscriber is created. By default, the subscriber must confirm the registration (double opt-in). Since a confirmation is required, the subscriber only appears in the subscriber list after the opt-in has been completed. To use this method, the corresponding create permissions for newsletter data are required.

Example

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

Request body

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

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create newsletters.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`email` is not a string or does not have a valid email format, `fields` is not an object, `targetGroupIds` is not an array of numbers, or one of the newsletter fields has an invalid value according to the validations configured in the shop.
400 Bad Request	”missing”	`email`, `fields` or `targetGroupIds` was not provided, `targetGroupIds` is an empty array, or one of the mandatory newsletter fields configured in the shop is not set.
400 Bad Request	”invalidValue”	`email` is an empty string.
400 Bad Request	”unknownDataField”	An attempt is being made to pass an unknown field. Only `email`, `fields` and `targetGroupIds` are allowed.
503 Service Unavailable		The double opt-in email could not be sent. The subscriber was not created.

This method updates the data of an existing newsletter subscriber by their ID. Only the fields email, fields (for example first name, last name) and targetGroupIds (target group membership) may be changed. Unknown parameters in the request body lead to an error.

Changing the email address

The email address is unique in the shop. If the new address already belongs to another subscriber, the request is rejected with 409 Conflict and the type "emailAlreadyExists". A change that only affects upper and lower case does not count as a change of the email address. If the email address is changed, the owner of the new address must confirm the change via double opt-in. To do this, the shop sends the double opt-in email from newsletter.newsletter → doubleOptInEmailSubscribe to the new address. The token contains the ID of the subscriber. After confirmation with NewsletterSubscribeConfirm, the new address is transferred to this subscriber. No additional subscriber is created and no welcome email is sent. Until confirmation, the following applies:

The stored email address remains unchanged.
All other changes from the request body, i.e. fields and targetGroupIds, are saved immediately and appear in changes.
The response additionally contains the field pendingEmail with the new, not yet confirmed address.

If the double opt-in email cannot be sent, the interface responds with 503 Service Unavailable. In this case, nothing is saved. To use this method, the corresponding write permissions for newsletter data are required.

Example

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

Request body

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

If email is also passed with a new address, the response still contains the previous address in email and the new address in pendingEmail:

{
    "email": "m.mustermann@websale.de",
    "pendingEmail": "max.mustermann@websale.de",
    ...
}

Response

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

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write newsletters.
400 Bad Request		Request body could not be loaded. `id` is invalid.
400 Bad Request	”invalidFormat”	`email` is not a string or does not have a valid email format, `fields` is not an object, `targetGroupIds` is not an array of numbers, or one of the newsletter fields has an invalid value according to the validations configured in the shop.
400 Bad Request	”missing”	`targetGroupIds` is an empty array, or one of the mandatory newsletter fields configured in the shop is not set.
400 Bad Request	”invalidValue”	`email` is an empty string.
400 Bad Request	”unknownDataField”	An attempt is being made to pass an unknown field. Only `email`, `fields` and `targetGroupIds` are allowed.
404 Not Found		No subscriber with `id={id}` exists.
409 Conflict	”emailAlreadyExists”	The new email address already belongs to another subscriber.
500 Internal Server Error	”internalError”	The subscriber could not be loaded. The check whether the new email address is already taken failed. The email address could not be changed directly without double opt-in.
503 Service Unavailable		The double opt-in email to the new email address could not be sent. Nothing was saved.

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.

​Supported methods

​Data fields for target groups and subscribers

​Data fields of a target group

​Example

​Data fields of a subscriber

​Example

​Methods for target groups

​GET newsletter/group

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET newsletter/group/{id}

​Example

​Response

​Error codes

​POST newsletter/group

​Example

​Request body

​Response

​Error codes

​PUT newsletter/group/{id}

​Example

​Request body

​Response

​Error codes

​DELETE newsletter/group/{id}

​Example

​Response

​Error codes

​Methods for subscribers

​GET newsletter/subscriber

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET newsletter/subscriber/{id}

​Example

​Response

​Error codes

​POST newsletter/subscriber/

​Example

​Request body

​Response

​Error codes

​PUT newsletter/subscriber/{id}

​Changing the email address

​Example

​Request body

​Response

​Error codes

​Support

Supported methods

Data fields for target groups and subscribers

Data fields of a target group

Example

Data fields of a subscriber

Example

Methods for target groups

GET newsletter/group

Example

Response

Filter fields

Sort fields

Error codes

GET newsletter/group/{id}

Example

Response

Error codes

POST newsletter/group

Example

Request body

Response

Error codes

PUT newsletter/group/{id}

Example

Request body

Response

Error codes

DELETE newsletter/group/{id}

Example

Response

Error codes

Methods for subscribers

GET newsletter/subscriber

Example

Response

Filter fields

Sort fields

Error codes

GET newsletter/subscriber/{id}

Example

Response

Error codes

POST newsletter/subscriber/

Example

Request body

Response

Error codes

PUT newsletter/subscriber/{id}

Changing the email address

Example

Request body

Response

Error codes

Support