Skip to main content
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.
CommandEndpointsGETPUTPOSTDELETE
List of newsletter target groups configured in the shopnewsletter/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

​
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. 
GET https://<your-shop>.de/api/v1/newsletter/targetGroups

​
Parameter overview

ParameterTypeDescription
——No additional parameters.

​
Example response

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

ParameterTypeDescription
emailstringRequired field
Email address that is to subscribe to the newsletter.
targetGroupIdsarray (number)List of target groups that should receive this subscription. The valid IDs are obtained via GET newsletter/targetGroups.
fieldsobjectObject with additional information about the subscriber. The keys and formats must correspond to the fields configured in newsletter.fields.

​
Error codes

CodeDescription
missingFieldA field marked as required is missing.
invalidFieldA value does not match the validation rules in the configuration. More about this: https://websale.atlassian.net/wiki/x/EQAZzg
invalidTargetGroupIdA specified target group ID does not exist.
deactivatedTargetGroupA 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 
POST https://<your-shop>.de/api/v1/newsletter/subscribeConfirm

​
Example request

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

​
Parameter overview

ParameterTypeDescription
otokstringRequired field
Opt-in token from the confirmation email.

​
Error codes

CodeDescription
actionNotAllowedThe opt-in token is invalid or expired for this action.
internalErrorInternal 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 
POST https://<your-shop>.de/api/v1/newsletter/unsubscribe

​
Example request

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

​
Parameter overview

ParameterTypeDescription
emailstringRequired field
Email address that is to be unsubscribed.
targetGroupIdsarray (int)List of target group IDs to unsubscribe from.

​
Error codes

CodeDescription
missingFieldA field marked as required is missing.
invalidFieldA value does not match the validation rules in the configuration. More about this: https://websale.atlassian.net/wiki/x/EQAZzg
invalidTargetGroupIdA specified target group ID does not exist.
deactivatedTargetGroupA 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 
POST https://<your-shop>.de/api/v1/newsletter/unsubscribeConfirm

​
Example request

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

​
Parameter overview

ParameterTypeDescription
otokstringRequired field
Opt-in token from the confirmation email.

​
Error codes

CodeDescription
actionNotAllowedThe opt-in token is invalid or expired for this action.
internalErrorInternal 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 
POST https://<your-shop>.de/api/v1/newsletter/blacklist

​
Example request

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

​
Parameter overview

ParameterTypeDescription
emailstringRequired field
The email address to be blocked.

​
Error codes

CodeDescription
emailCheckFailedThe 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 
POST https://<your-shop>.de/api/v1/newsletter/blacklistConfirm

​
Example request

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

​
Parameter overview

ParameterTypeDescription
otokstringRequired field
Opt-in token from the confirmation email.

​
Error codes

CodeDescription
actionNotAllowedThe opt-in token is invalid or expired for this action.