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

# Storefront API Newsletter

> Integrate WEBSALE newsletter sign-ups and sign-offs into the storefront via the Storefront API with target groups and double opt-in confirmation flows.

The Newsletter API is used to integrate newsletter sign-ups and sign-offs for the WEBSALE newsletter module in the storefront. It can be used for both logged-in customers and anonymous visitors and represents the usual opt-in/opt-out processes in the frontend.

***

## Supported methods

List of all supported methods.

| **Command**                                             | **Endpoints**                   | **GET**               | **PUT**             | **POST**              | **DELETE**          |
| ------------------------------------------------------- | ------------------------------- | --------------------- | ------------------- | --------------------- | ------------------- |
| List of newsletter target groups configured in the shop | `newsletter/targetGroups`       | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Creates a new newsletter subscription.                  | `newsletter/subscribe`          | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Confirms a new newsletter subscription.                 | `newsletter/subscribeConfirm`   | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Unsubscribe from the newsletter.                        | `newsletter/unsubscribe`        | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Confirmation of the newsletter unsubscription.          | `newsletter/unsubscribeConfirm` | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Adds an email address to the blocklist.                 | `newsletter/blacklist`          | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Confirms blocking of the email address.                 | `newsletter/blacklistConfirm`   | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |

## Methods for the newsletter

These methods control the complete newsletter management in the shop: They read out the configured target groups and enable the creation, confirmation (double opt-in), and termination of newsletter subscriptions — optionally per target group. Additionally, email addresses can be permanently excluded from sending via a blacklist, which is also secured via a confirmation link. Validations and typical error cases (e.g. missing required fields, invalid target groups, or incorrect or expired opt-in tokens) are reported back via defined error codes.

### GET newsletter/targetGroups

The following call returns all newsletter target groups configured in the shop. It can be used to display selectable target groups in the newsletter sign-up form or on profile/settings pages.

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

#### Parameter overview

| **Parameter** | **Type** | **Description**           |
| ------------- | -------- | ------------------------- |
| --            | --       | No additional parameters. |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "items": [
    { "deactivated": false, "id": 1, "name": "foo" },
    { "deactivated": false, "id": 2, "name": "asdf" }
  ]
}
```

## POST newsletter/subscribe

The following call creates a newsletter subscription for an email address and optionally assigns target groups. If the double opt-in procedure is enabled, a confirmation email is sent first. The subscription is only active after confirmation. It can be used for sign-up forms with the selection of target groups and the entry of additional fields.

**Example call that creates a newsletter subscription for the customer account with the email address** `maria.musterfrau@example.com` **and the newsletter groups** `1` **and** `2`**. First and last name are passed along as optional additional information**

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

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "email": "maria.musterfrau@example.com",
  "targetGroupIds": [1, 2],
  "fields": {
    "firstName": "Maria",
    "lastName": "Musterfrau"
  }
}
```

#### Parameter overview

| **Parameter**    | **Type**       | **Description**                                                                                                                                |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`          | string         | **Required field**<br />Email address that is to subscribe to the newsletter.                                                                  |
| `targetGroupIds` | array (number) | List of target groups that should receive this subscription. The valid IDs are obtained via `GET newsletter/targetGroups`.                     |
| `fields`         | object         | Object with additional information about the subscriber. The keys and formats must correspond to the fields configured in `newsletter.fields`. |

#### Error codes

| **Code**                 | **Description**                                                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `missingField`           | A field marked as required is missing.                                                                                                                                          |
| `invalidField`           | A value does not match the validation rules in the configuration.   More about this: [https://websale.atlassian.net/wiki/x/EQAZzg](https://websale.atlassian.net/wiki/x/EQAZzg) |
| `invalidTargetGroupId`   | A specified target group ID does not exist.                                                                                                                                     |
| `deactivatedTargetGroup` | A specified target group is deactivated or does not accept new subscribers.                                                                                                     |

### POST newsletter/subscribeConfirm

The following call can be used to confirm a newsletter subscription previously started via "Newsletter/Subscribe" by opt-in token. This activates the subscription for the specified email address. It can be used for handling in the double opt-in email.

**Example call that confirms the newsletter subscription using the confirmation code from the email**

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

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "otok": "<code from the email>"
}
```

#### Parameter overview

| **Parameter** | **Type** | **Description**                                                   |
| ------------- | -------- | ----------------------------------------------------------------- |
| `otok`        | string   | **Required field**<br />Opt-in token from the confirmation email. |

#### Error codes

| **Code**           | **Description**                                         |
| ------------------ | ------------------------------------------------------- |
| `actionNotAllowed` | The opt-in token is invalid or expired for this action. |
| `internalError`    | Internal error; can only be resolved by WEBSALE.        |

### POST newsletter/unsubscribe

The following call can be used to unsubscribe from the newsletter — if desired, only from certain target groups. If the double opt-in procedure is enabled, an additional confirmation email may be required. This can be used, for example, for an unsubscribe form or an unsubscribe link.

**Example call that unsubscribes the customer account with the email** `maria.musterfrau@example.com` **from the newsletter target groups** `1` **and** `2`

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

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "email": "maria.musterfrau@example.com",
  "targetGroupIds": [1, 2]
}
```

#### Parameter overview

| **Parameter**    | **Type**    | **Description**                                                   |
| ---------------- | ----------- | ----------------------------------------------------------------- |
| `email`          | string      | **Required field**<br />Email address that is to be unsubscribed. |
| `targetGroupIds` | array (int) | List of target group IDs to unsubscribe from.                     |

#### Error codes

| **Code**                 | **Description**                                                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `missingField`           | A field marked as required is missing.                                                                                                                                          |
| `invalidField`           | A value does not match the validation rules in the configuration.   More about this: [https://websale.atlassian.net/wiki/x/EQAZzg](https://websale.atlassian.net/wiki/x/EQAZzg) |
| `invalidTargetGroupId`   | A specified target group ID does not exist.                                                                                                                                     |
| `deactivatedTargetGroup` | A specified target group is deactivated or does not accept new subscribers.                                                                                                     |

### POST newsletter/unsubscribeConfirm

The following call can be used to confirm and finally complete a newsletter unsubscription that took place via opt-in token from the confirmation email. It can be used for handling the unsubscription email.

**Example call that terminates the newsletter subscription using the confirmation code from the email**

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

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "otok": "<code from the email>"
}
```

#### Parameter overview

| **Parameter** | **Type** | **Description**                                                   |
| ------------- | -------- | ----------------------------------------------------------------- |
| otok          | string   | **Required field**<br />Opt-in token from the confirmation email. |

#### Error codes

| **Code**           | **Description**                                         |
| ------------------ | ------------------------------------------------------- |
| `actionNotAllowed` | The opt-in token is invalid or expired for this action. |
| `internalError`    | Internal error; can only be resolved by WEBSALE.        |

### POST newsletter/blacklist

The following call puts an email address on the blocklist so that no more newsletters are sent to this address. The block can be lifted again by re-subscribing. This can be used, for example, for opt-out functions such as "no longer receive any newsletters".

**Example call that puts the email address** `maria.musterfrau@websale.de` **on the blocklist**

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

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "email": "maria.musterfrau@websale.de"
}
```

#### Parameter overview

| **Parameter** | **Type** | **Description**                                          |
| ------------- | -------- | -------------------------------------------------------- |
| `email`       | string   | **Required field**<br />The email address to be blocked. |

#### Error codes

| **Code**           | **Description**                         |
| ------------------ | --------------------------------------- |
| `emailCheckFailed` | The specified email address is invalid. |

### POST newsletter/blacklistConfirm

The following call confirms the previously requested block (adding to the blocklist) of an email address by opt-in token from the confirmation email. Used to complete the blocklist process after clicking the link from the email.

**Example call that uses the confirmation code from the email to add the email address to the blocklist**

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

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "otok": "<code from the email>"
}
```

#### Parameter overview

| **Parameter** | **Type** | **Description**                                                   |
| ------------- | -------- | ----------------------------------------------------------------- |
| otok          | string   | **Required field**<br />Opt-in token from the confirmation email. |

#### Error codes

| **Code**           | **Description**                                         |
| ------------------ | ------------------------------------------------------- |
| `actionNotAllowed` | The opt-in token is invalid or expired for this action. |