Storefront API Newsletter

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`
Creates a new newsletter subscription.	`newsletter/subscribe`
Confirms a new newsletter subscription.	`newsletter/subscribeConfirm`
Unsubscribe from the newsletter.	`newsletter/unsubscribe`
Confirmation of the newsletter unsubscription.	`newsletter/unsubscribeConfirm`
Adds an email address to the blocklist.	`newsletter/blacklist`
Confirms blocking of the email address.	`newsletter/blacklistConfirm`

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

GET https://<your-shop>.de/api/v1/newsletter/targetGroups

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

{
  "items": [
    { "deactivated": false, "id": 1, "name": "foo" },
    { "deactivated": false, "id": 2, "name": "asdf" }
  ]
}

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

POST https://<your-shop>.de/api/v1/newsletter/subscribe

Example request

{
  "email": "maria.musterfrau@example.com",
  "targetGroupIds": [1, 2],
  "fields": {
    "firstName": "Maria",
    "lastName": "Musterfrau"
  }
}

Parameter overview

Parameter	Type	Description
`email`	string	Required field 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
`invalidTargetGroupId`	A specified target group ID does not exist.
`deactivatedTargetGroup`	A specified target group is deactivated or does not accept new subscribers.

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

POST https://<your-shop>.de/api/v1/newsletter/subscribeConfirm

Example request

{
  "otok": "<code from the email>"
}

Parameter overview

Parameter	Type	Description
`otok`	string	Required field 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.

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

POST https://<your-shop>.de/api/v1/newsletter/unsubscribe

Example request

{
  "email": "maria.musterfrau@example.com",
  "targetGroupIds": [1, 2]
}

Parameter overview

Parameter	Type	Description
`email`	string	Required field 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
`invalidTargetGroupId`	A specified target group ID does not exist.
`deactivatedTargetGroup`	A specified target group is deactivated or does not accept new subscribers.

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

POST https://<your-shop>.de/api/v1/newsletter/unsubscribeConfirm

Example request

{
  "otok": "<code from the email>"
}

Parameter overview

Parameter	Type	Description
otok	string	Required field 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.

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

POST https://<your-shop>.de/api/v1/newsletter/blacklist

Example request

{
  "email": "maria.musterfrau@websale.de"
}

Parameter overview

Parameter	Type	Description
`email`	string	Required field The email address to be blocked.

Error codes

Code	Description
`emailCheckFailed`	The specified email address is invalid.

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

POST https://<your-shop>.de/api/v1/newsletter/blacklistConfirm

Example request

{
  "otok": "<code from the email>"
}

Parameter overview

Parameter	Type	Description
otok	string	Required field Opt-in token from the confirmation email.

Error codes

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

Interfaces

Admin Interface API

Storefront API

More

Supported methods

Parameter overview

Example response

Example request

Parameter overview

Error codes

Example request

Parameter overview

Error codes

Example request

Parameter overview

Error codes

Example request

Parameter overview

Error codes

Example request

Parameter overview

Error codes

Example request

Parameter overview

Error codes

​Supported methods

​Methods for the newsletter

​GET newsletter/targetGroups

​Parameter overview

​Example response

​POST newsletter/subscribe

​Example request

​Parameter overview

​Error codes

​POST newsletter/subscribeConfirm

​Example request

​Parameter overview

​Error codes

​POST newsletter/unsubscribe

​Example request

​Parameter overview

​Error codes

​POST newsletter/unsubscribeConfirm

​Example request

​Parameter overview

​Error codes

​POST newsletter/blacklist

​Example request

​Parameter overview

​Error codes

​POST newsletter/blacklistConfirm

​Example request

​Parameter overview

​Error codes

Supported methods

Methods for the newsletter

GET newsletter/targetGroups

Parameter overview

Example response

POST newsletter/subscribe

Example request

Parameter overview

Error codes

POST newsletter/subscribeConfirm

Example request

Parameter overview

Error codes

POST newsletter/unsubscribe

Example request

Parameter overview

Error codes

POST newsletter/unsubscribeConfirm

Example request

Parameter overview

Error codes

POST newsletter/blacklist

Example request

Parameter overview

Error codes

POST newsletter/blacklistConfirm

Example request

Parameter overview

Error codes