> ## 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 reference newsletter

> Manage newsletter subscribers and target groups via the Admin Interface API: create, list, update, and segment recipients for shop campaigns.

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      | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> |
| **Subscribers**   | newsletter/subscriber | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="ban" />   |

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

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

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

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

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

### GET newsletter/group

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/newsletter/group
```

#### Response

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

#### 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.<br />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 ":".                      |

### GET newsletter/group/\{id}

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/newsletter/group/2
```

#### Response

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

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

### POST newsletter/group

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.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"
}
```

#### Response

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

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

### PUT newsletter/group/\{id}

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.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"
}
```

#### Response

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

#### 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.<br />`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.                               |

### DELETE newsletter/group/\{id}

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/newsletter/group/2
```

#### Response

The target group is deactivated successfully.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

### GET newsletter/subscriber

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/newsletter/subscriber
```

#### Response

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

#### 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] <br /> `pageToken` is not a number or is less than 0. |
| 400 Bad Request         | "invalidCharacters" | `size` is not an integer. <br /> 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.                           |

### GET newsletter/subscriber/\{id}

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/newsletter/subscriber/1
```

#### Response

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

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

### POST newsletter/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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.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
    ]
}
```

#### Response

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

#### 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 service cannot be reached.                                                                                                                                                                                                     |

### PUT newsletter/subscriber/\{id}

This method updates the data of an existing newsletter subscriber by their ID.

Only the fields `email`, `fields` (e.g. first name, last name) and `targetGroupIds` (target group membership) may be changed. Unknown parameters in the request body lead to an error.

If the email address is changed, the owner must confirm the registration again. Until this happens, the address remains unchanged.

To use this method, the corresponding write permissions for newsletter data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.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
    ]
}
```

#### Response

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

#### 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.<br />`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.                                                                                                                                                                                                             |
| 503 Service Unavailable |                    | Internal error while loading the subscriber.<br />The double opt-in service cannot be reached (only when changing the email address).                                                                                                            |

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