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

> Newsletter-Anmeldungen und -Abmeldungen für eingeloggte Kunden und anonyme Besucher über die Storefront API als Opt-in/Opt-out abbilden.

Die Newsletter API dient zur Integration von Newsletter-Anmeldungen und -Abmeldungen für das WEBSALE Newsletter-Modul in der Storefront. Sie kann sowohl für eingeloggte Kunden als auch für anonyme Besucher verwendet werden und bildet die üblichen Opt-in/Opt-out-Vorgänge im Frontend ab.

***

## Unterstützte Methoden

Angabe aller unterstützten Methoden.

| **Befehl**                                              | **Endpunkte**                   | **GET**               | **PUT**             | **POST**              | **DELETE**          |
| ------------------------------------------------------- | ------------------------------- | --------------------- | ------------------- | --------------------- | ------------------- |
| Liste der im Shop konfigurierten Newsletter-Zielgruppen | `newsletter/targetGroups`       | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" /> |
| Erstellt ein neues Newsletter-Abo.                      | `newsletter/subscribe`          | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Bestätigt ein neues Newsletter-Abo.                     | `newsletter/subscribeConfirm`   | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Abmeldung vom Newsletter.                               | `newsletter/unsubscribe`        | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Bestätigung der Abmeldung vom Newsletter.               | `newsletter/unsubscribeConfirm` | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Setzt eine E-Mail-Adresse auf die Sperrliste.           | `newsletter/blacklist`          | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |
| Bestätigt die Sperre der E-Mail-Adresse.                | `newsletter/blacklistConfirm`   | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |

## Methoden für den Newsletter

Mithilfe dieser Methoden wird das komplette Newsletter-Management im Shop gesteuert: Sie lesen die konfigurierten Zielgruppen aus und ermöglichen das Anlegen, Bestätigen (Double-Opt-In) und Beenden von Newsletter-Abos – optional je Zielgruppe. Zusätzlich können E-Mail-Adressen dauerhaft über eine Blacklist vom Versand ausgeschlossen werden, was ebenfalls per Bestätigungslink abgesichert ist. Validierungen und typische Fehlerfälle (z. B. fehlende Pflichtfelder, ungültige Zielgruppen oder falsche bzw. abgelaufene Opt-in-Tokens) werden dabei über definierte Fehlercodes zurückgemeldet.

### GET newsletter/targetGroups

Der folgende Aufruf liefert alle im Shop konfigurierten Newsletter-Zielgruppen. Er kann verwendet werden, um beim Newsletter-Anmeldeformular oder auf Profil-/Einstellungsseiten auswählbare Zielgruppen anzuzeigen.

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

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**              |
| ------------- | ------- | ----------------------------- |
| --            | --      | Keine zusätzlichen Parameter. |

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

Mit folgendem Aufruf wird für eine E-Mail-Adresse ein Newsletter-Abo angelegt und optional Zielgruppen zugeordnet. Bei aktiviertem Double-Opt-In-Verfahren wird zuerst eine Bestätigungs-E-Mail verschickt. Das Abonnement ist erst nach Bestätigung aktiv. Es ist für Anmeldeformulare mit Auswahl von Zielgruppen und Erfassung zusätzlicher Felder verwendbar.

**Beispiel-Aufruf, der ein Newsletter-Abo für das Kundenkonto mit der E-Mail-Adresse** `maria.musterfrau@example.com `**und die Newslettergruppen** `1 `**und** `2 `**anlegt. Als optionale Zusatzinformationen wird der Vor- und Nachname mitgegeben**

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

#### Beispiel-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übersicht

| **Parameter**    | **Typ**        | **Beschreibung**                                                                                                                                |
| ---------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`          | string         | **Pflichtfeld**<br />E-Mail-Adresse, die den Newsletter abonnieren soll.                                                                        |
| `targetGroupIds` | array (number) | Liste von Zielgruppen, die dieses Abo erhalten soll. Die gültigen IDs erhält man über `GET newsletter/targetGroups`.                            |
| `fields`         | object         | Objekt mit zusätzlichen Angaben zum Abonnenten. Die Schlüssel und Formate müssen den in `newsletter.fields` konfigurierten Feldern entsprechen. |

#### Fehlercodes

| **Code**                 | **Beschreibung**                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `missingField`           | Ein als Pflichtfeld markiertes Feld fehlt.                                                                                                                                     |
| `invalidField`           | Ein Wert entspricht nicht den Validierungsregeln in der Konfiguration.   Mehr dazu: [https://websale.atlassian.net/wiki/x/EQAZzg](https://websale.atlassian.net/wiki/x/EQAZzg) |
| `invalidTargetGroupId`   | Eine angegebene Zielgruppen-ID existiert nicht.                                                                                                                                |
| `deactivatedTargetGroup` | Eine angegebene Zielgruppe ist deaktiviert oder nimmt keine neuen Abonnenten auf.                                                                                              |

### POST newsletter/subscribeConfirm

Mit dem folgenden Aufruf kann ein zuvor über „Newsletter/Subscribe” gestartetes Newsletter-Abo per Opt-In-Token bestätigt werden. Dadurch wird das Abo für die angegebene E-Mail-Adresse aktiviert. Er ist für das Handling in der Double-Opt-In-E-Mail verwendbar.

**Beispiel-Aufruf, der mithilfe des Bestätigungscodes aus der E-Mail das Newsletter-Abo bestätigt**

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

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "otok": "<Code aus der Mail>"
}
```

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**                                               |
| ------------- | ------- | -------------------------------------------------------------- |
| `otok`        | string  | **Pflichtfeld**<br />Opt-In-Token aus der Bestätigungs-E-Mail. |

#### Fehlercodes

| **Code**           | **Beschreibung**                                                |
| ------------------ | --------------------------------------------------------------- |
| `actionNotAllowed` | Der Opt-In-Token ist für diese Aktion ungültig oder abgelaufen. |
| `internalError`    | Interner Fehler; kann nur von WEBSALE behoben werden.           |

### POST newsletter/unsubscribe

Mit folgendem Aufruf kann man sich vom Newsletter abmelden – auf Wunsch auch nur aus bestimmten Zielgruppen. Bei aktiviertem Double-Opt-In-Verfahren ist unter Umständen eine zusätzliche Bestätigungs-E-Mail erforderlich. Dies ist beispielsweise für ein Abmeldeformular oder einen Abmelde-Link nutzbar.

**Beispiel-Aufruf, der das Kundenkonto mit der E-Mail** `maria.musterfrau@example.com `**von den Newsletter-Zielgruppen** `1 `**und** `2 `**abmeldet**

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

#### Beispiel-Request

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

#### Parameterübersicht

| **Parameter**    | **Typ**     | **Beschreibung**                                                 |
| ---------------- | ----------- | ---------------------------------------------------------------- |
| `email`          | string      | **Pflichtfeld**<br />E-Mail-Adresse, die abgemeldet werden soll. |
| `targetGroupIds` | array (int) | Liste der Zielgruppen-IDs, aus denen abgemeldet werden soll.     |

#### Fehlercodes

| **Code**                 | **Beschreibung**                                                                                                                                                               |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `missingField`           | Ein als Pflichtfeld markiertes Feld fehlt.                                                                                                                                     |
| `invalidField`           | Ein Wert entspricht nicht den Validierungsregeln in der Konfiguration.   Mehr dazu: [https://websale.atlassian.net/wiki/x/EQAZzg](https://websale.atlassian.net/wiki/x/EQAZzg) |
| `invalidTargetGroupId`   | Eine angegebene Zielgruppen-ID existiert nicht.                                                                                                                                |
| `deactivatedTargetGroup` | Eine angegebene Zielgruppe ist deaktiviert oder nimmt keine neuen Abonnenten auf.                                                                                              |

### POST newsletter/unsubscribeConfirm

Mit dem folgenden Aufruf kann eine per Opt-In-Token aus der Bestätigungs-E-Mail erfolgte Newsletter-Abmeldung bestätigt und endgültig abgeschlossen werden. Er ist für das Handling der Abmelde-E-Mail verwendbar.

**Beispiel-Aufruf, der mithilfe des Bestätigungscodes aus der E-Mail das Newsletter-Abo beendet**

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

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "otok": "<Code aus der Mail>"
}
```

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**                                               |
| ------------- | ------- | -------------------------------------------------------------- |
| otok          | string  | **Pflichtfeld**<br />Opt-In-Token aus der Bestätigungs-E-Mail. |

#### Fehlercodes

| **Code**           | **Beschreibung**                                                |
| ------------------ | --------------------------------------------------------------- |
| `actionNotAllowed` | Der Opt-In-Token ist für diese Aktion ungültig oder abgelaufen. |
| `internalError`    | Interner Fehler; kann nur von WEBSALE behoben werden.           |

### POST newsletter/blacklist

Mit dem folgenden Aufruf wird eine E-Mail-Adresse auf die Sperrliste gesetzt, sodass an diese Adresse keine Newsletter mehr versendet werden. Die Sperre kann durch erneutes Abonnieren wieder aufgehoben werden. Dies ist beispielsweise für Opt-Out-Funktionen wie „Keine Newsletter mehr erhalten“ verwendbar.

**Beispiel-Aufruf, der die E-Mail-Adresse** `maria.musterfrau@websale.de `**auf die Sperrliste setzt**

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

#### Beispiel-Request

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

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**                                      |
| ------------- | ------- | ----------------------------------------------------- |
| `email`       | string  | **Pflichtfeld**<br />Die zu sperrende E-Mail-Adresse. |

#### Fehlercodes

| **Code**           | **Beschreibung**                            |
| ------------------ | ------------------------------------------- |
| `emailCheckFailed` | Die angegebene E-Mail-Adresse ist ungültig. |

### POST newsletter/blacklistConfirm

Folgender Aufruf bestätigt die zuvor angeforderte Sperre (auf die Sperrliste setzen) einer E-Mail-Adresse per Opt-In-Token aus der Bestätigungs-Mail. Verwendbar für den Abschluss des Sperrlisten-Prozesses nach Klick auf den Link aus der E-Mail.

**Beispiel-Aufruf, der mithilfe des Bestätigungscodes aus der E-Mail die E-Mail-Adresse auf die Sperrliste setzt**

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

#### Beispiel-Request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "otok": "<Code aus der Mail>"
}
```

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**                                               |
| ------------- | ------- | -------------------------------------------------------------- |
| otok          | string  | **Pflichtfeld**<br />Opt-In-Token aus der Bestätigungs-E-Mail. |

#### Fehlercodes

| **Code**           | **Beschreibung**                                                |
| ------------------ | --------------------------------------------------------------- |
| `actionNotAllowed` | Der Opt-In-Token ist für diese Aktion ungültig oder abgelaufen. |