Newsletter

This section describes the available actions in the Newsletter area. Using these actions, customers can subscribe to the newsletter, confirm their subscription, unsubscribe again, or have their email address blocked from receiving newsletters.

Actions overview

Action	Description
`NewsletterSubscribe`	Subscribes a customer to the newsletter.
`NewsletterSubscribeConfirm`	Confirms the newsletter subscription via double opt-in.
`NewsletterUnsubscribe`	Unsubscribes a customer from the newsletter.
`NewsletterUnsubscribeConfirm`	Confirms the newsletter unsubscription via double opt-in.
`BlacklistAdd`	Adds an email address to the blacklist.
`BlacklistAddConfirm`	Confirms the blacklist entry via double opt-in.

Actions

NewsletterSubscribe

This action subscribes a customer to the newsletter. After successful subscription, the customer receives a confirmation email with a double opt-in link. Usage example
Can be used on a newsletter subscription page where customers can enter their email address and optionally select one or more target groups. Parameters

Name	Description
`email`	The email address to be subscribed to the newsletter.
`targetGroupId.(id)`	Optional target group ID to which the customer should be subscribed.

Error codes

Error code	Description
`missingEmail`	Parameter `email` is missing.
`emailCheckFailed`	The specified email address is invalid.
`accountAlreadyExists`	The email address is already subscribed to the newsletter.

Related modules, variables & methods

Example showing how a customer selects their email address and optionally target groups to subscribe to the newsletter, including success output after the subscription.

{{ var $myActionNewsletterSubscribe = $wsActions.create("NewsletterSubscribe") }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionNewsletterSubscribe.csrf }}">
    <input type="hidden" name="wsact" value="{{= $myActionNewsletterSubscribe.id }}">
    {{ if $myActionNewsletterSubscribe.success }}
        <div class="alert alert-success">Newsletter successfully subscribed.</div>
    {{ /if }}
    {{ foreach $myNewsletterList in $wsNewsletter.getTargetGroups() }}
        <input type="checkbox" value="{{= $myNewsletterList.id }}" name="targetGroupId.{{= $myNewsletterList.id }}">
        <label>{{= $myNewsletterList.name }}</label>
    {{ /foreach }}
    <input type="email" name="email">
    <button type="submit">Subscribe to newsletter</button>
</form>

NewsletterSubscribeConfirm

This action confirms the newsletter subscription via double opt-in. After subscribing, the customer receives an email with a confirmation link that triggers this action. For a regular subscription, the action either creates a new subscriber or adds the selected target groups to an existing subscriber with the same email address. The address is then removed from the blacklist and the welcome email is sent. Usage example
Can be used on the confirmation page to which the customer is redirected after clicking the opt-in link in the subscription email. Confirming a changed email address If a subscriber’s email address is changed via PUT newsletter/subscriber/{id}, the new address also receives an email with the token confirmSubscribeNewsletter. This token additionally contains the parameter subscriberId with the ID of the existing subscriber. If the token contains a subscriberId, no new subscriber is created. Instead, the confirmed email address is assigned to the existing subscriber:

Situation	Result
The subscriber exists and the address is available	The subscriber’s email address is replaced and recorded in the change history. Target groups and newsletter fields remain unchanged. The address is removed from the blacklist. No welcome email is sent. The action is successful.
The address now belongs to another subscriber	Nothing is changed. The action is still successful.
The subscriber has since been deleted or the change fails	The action reports the error code `internalError`.

Tokens without a subscriberId, for example from a subscription via the NewsletterSubscribe function or from emails sent before this parameter was introduced, continue to be processed like regular subscriptions. Error codes The error texts are maintained in actions.newsletterSubscribe.

Error code	Description
`actionNotAllowed`	No valid opt-in token was passed for this action.
`internalError`	The token contains no email address or no target group, the subscriber data could not be loaded, or the email address could not be transferred to the existing subscriber.

Related modules, variables & methods

$wsNewsletter

Example showing how a success message is displayed after successful confirmation and an error notice appears in the event of an invalid token.

{{ var $myActionNewsletterSubscribeConfirm = $wsActions.create('NewsletterSubscribeConfirm') }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionNewsletterSubscribeConfirm.csrf }}">
    <input type="hidden" name="wsact" value="{{= $myActionNewsletterSubscribeConfirm.id }}">
    {{ if $myActionNewsletterSubscribeConfirm.success }}
        <div class="alert alert-success">Newsletter successfully subscribed.</div>
    {{ else }}
        {{ include "components/errorAlert.htm" with $cAction = $cActionNewsletterSubscribeConfirm }}
        <button type="submit">Confirm subscription.</button>
    {{ /if }}
</form>

NewsletterUnsubscribe

This action unsubscribes a customer from the newsletter. The customer specifies their email address and can optionally deselect individual target groups. Usage example
Can be used on the unsubscribe page, where customers can enter their email address and unsubscribe from individual or all newsletter target groups. Parameters

Name	Description
`email`	The email address to be unsubscribed from the newsletter.
`targetGroupId.(id)`	Optional target group ID from which the customer should be unsubscribed.

Error codes

Error code	Description
`missingEmail`	Parameter `email` is missing.
`emailCheckFailed`	The specified email address is invalid.

Related modules, variables & methods

Example showing how a customer enters their email address and unsubscribes from individual target groups, including success output.

{{ var $myActionNewsletterUnsubscribe = $wsActions.create('NewsletterUnsubscribe') }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionNewsletterUnsubscribe.csrf }}">
    <input type="hidden" name="wsact" value="{{= $myActionNewsletterUnsubscribe.id }}">
    {{ if $cActionNewsletterUnsubscribe.success }}
        <div class="alert alert-success">Successfully unsubscribed from the newsletter.</div>
    {{ else }}
        <input type="email" name="email" value="{{= $myActionNewsletterUnsubscribe.params.email | ifNull('') }}">
        {{ foreach $group in $wsNewsletter.getTargetGroups() }}
            {{ if not $group.deactivated }}
                <input type="checkbox" name="targetGroupId.{{= $group.id }}" value="y">
                <label>{{= $group.name }}</label>
            {{ /if }}
        {{ /foreach }}
        <button type="submit">Unsubscribe from newsletter.</button>
    {{ /if }}
</form>

NewsletterUnsubscribeConfirm

This action confirms the newsletter unsubscription via double opt-in. After unsubscribing, the customer receives an email with a confirmation link that triggers this action. Usage example
Can be used on the confirmation page to which the customer is redirected after clicking the opt-in link in the unsubscription email. Error codes The error texts are maintained in actions.newsletterUnsubscribe.

Error code	Description
`actionNotAllowed`	No valid opt-in token was passed for this action.
`internalError`	The token contains no email address or no target group.

Related modules, variables & methods

$wsNewsletter

Example showing how a success message is displayed after successful confirmation of the unsubscription and an error notice appears in the event of an invalid token.

{{ var $myActionNewsletterUnsubscribeConfirm = $wsActions.create('NewsletterUnsubscribeConfirm') }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionNewsletterUnsubscribeConfirm.csrf }}">
    <input type="hidden" name="wsact" value="{{= $myActionNewsletterUnsubscribeConfirm.id }}">
    {{ if $cActionNewsletterUnsubscribeConfirm.success }}
        <div class="alert alert-success">Successfully unsubscribed from the newsletter.</div>
    {{ else }}
        <button type="submit">Confirm unsubscription.</button>
    {{ /if }}
</form>

BlacklistAdd

This action adds an email address to the blacklist (block list). The shop does not send newsletters to addresses on this list. The block applies to all subshops and all target groups. Whether the owner of the address must confirm the entry is controlled by the parameter blacklistSelfDoubleOptIn in newsletter.newsletter:

blacklistSelfDoubleOptIn inactive: The address is added to the blacklist immediately.
blacklistSelfDoubleOptIn active: The shop sends the email from newsletter.newsletter → doubleOptInEmailBlacklist with an opt-in link to the address. Only the confirmation with BlacklistAddConfirm adds the address to the blacklist. In the email template, you generate the link with the token name confirmBlacklistAdd, see $wsOptIn.

In both cases, the action reports success as soon as the input is valid. Usage example
Can be used on a page where customers can permanently exclude their email address from receiving newsletters. Parameters

Name	Description
`email`	The email address to be added to the blacklist.

Error codes The error texts come from actions.newsletterSubscribe.

Error code	Description
`missingField`	Parameter `email` is missing or empty.
`emailCheckFailed`	The specified email address is invalid.

Related modules, variables & methods

$wsOptIn

Example showing how a customer enters their email address to have it added to the blacklist, including success output.

{{ var $myActionBlacklistAdd = $wsActions.create('BlacklistAdd') }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionBlacklistAdd.csrf }}">
    <input type="hidden" name="wsact" value="{{= $myActionBlacklistAdd.id }}">
    {{ if $myActionBlacklistAdd.success }}
        <div class="alert alert-success">Your request has been saved.</div>
    {{ else }}
        <input type="email" name="email">
        <button type="submit">Exclude from newsletter mailings</button>
    {{ /if }}
</form>

BlacklistAddConfirm

This action confirms the entry of an email address in the blacklist via double opt-in. The action takes the email address from the opt-in token and adds it to the blacklist. Usage example
Can be used on the confirmation page to which the customer is redirected after clicking the opt-in link in the email from BlacklistAdd. Error codes The error texts are maintained in actions.blacklistAdd.

Error code	Description
`actionNotAllowed`	No valid opt-in token was passed for this action.

Related modules, variables & methods

$wsOptIn

Example showing how a success message is displayed after successful confirmation and an error notice appears in the event of an invalid token.

{{ var $myActionBlacklistAddConfirm = $wsActions.create('BlacklistAddConfirm') }}
<form method="post" action="{{= $wsViews.current.url() }}">
    <input type="hidden" name="wscsrf" value="{{= $myActionBlacklistAddConfirm.csrf }}">
    <input type="hidden" name="wsact" value="{{= $myActionBlacklistAddConfirm.id }}">
    {{ if $myActionBlacklistAddConfirm.success }}
        <div class="alert alert-success">Your email address has been excluded from newsletter mailings.</div>
    {{ else }}
        {{ foreach $myError in $myActionBlacklistAddConfirm.globalErrors }}
            <div class="alert alert-danger">{{= $myError.text }}</div>
        {{ /foreach }}
        <button type="submit">Confirm entry</button>
    {{ /if }}
</form>

Frontend

The basics

Getting started

Feature overview

Examples

Reference – Actions

Reference – Language

Reference – Modules

Actions overview

Actions

NewsletterSubscribe

NewsletterSubscribeConfirm

NewsletterUnsubscribe

NewsletterUnsubscribeConfirm

BlacklistAdd

BlacklistAddConfirm

​Actions overview

​Actions

​NewsletterSubscribe

​NewsletterSubscribeConfirm

​NewsletterUnsubscribe

​NewsletterUnsubscribeConfirm

​BlacklistAdd

​BlacklistAddConfirm

Actions overview

Actions

NewsletterSubscribe

NewsletterSubscribeConfirm

NewsletterUnsubscribe

NewsletterUnsubscribeConfirm

BlacklistAdd

BlacklistAddConfirm