Managing opt-ins

Let your customers subscribe for or unsubscribe of newsletters in your web shop. The data, which includes not only the email address but also other customer data such as name, address or areas of interest, is written in fields of the Optimizely Campaign recipient list. You can update this data afterwards.

Your shop system is considered the leading system that collects the data and forwards it to Optimizely Campaign. In the case of opt-inUsed in Optimizely Campaign. An opt-in method requires recipients to give a sender explicit permission to send them advertising mails. and opt-out processes, you must ensure that the customer is logged in or out of the web shop after clicking the respective confirmation link. This is done, for example, via a confirmation page, which you use to process an additional recipient ID parameter.

Structure of the recipient list

To adjust the structure of the recipient lists in Optimizely Campaign, you define in advance which user data from your shop system should be synchronized with Optimizely Campaign. Contact customer support to configure the recipient list so that the names of the recipient list fields conform to Optimizely conventions.

In addition to the email address and the personal data, the recipient list must contain an ID field to identify the data record in the shop system. You should ideally use a coded hash value.

Specify the bmOptinSource field, which indicates the source of the opt-in. Enter a string such as ShopSystem/ShopName/Version, for example WebShop/Shoe Shop/1.1.2.

Overview of the opt-in process

If a customer is to register for a newsletter from the shop system, the opt-in process consists of the following steps:

  1. Your shop system requests the Optimizely Campaign HTTP API and initiates the opt-in process. In addition to the email address, an ID is also transferred to identify the data record in the web shop.
  2. Optimizely Campaign sends the recipient an email requesting to confirm the registration by clicking a confirmation link.
  3. The recipient clicks on the confirmation link.
  4. Optimizely Campaign registers the confirmation and the recipient appears in the opt-in recipient list.
  5. Optimizely Campaign redirects the recipient via HTTP forwarding to the web shop and adds the parameter used to identify the data record in the web shop to the URL; for example https://www.example.com/newsletter/success?id=781278TZ.

    You must provide the URL of the confirmation page for the opt-in process in Optimizely Campaign in advance.

  6. The integration in the web shop accepts the request under /newsletter/success and accesses the value of the id parameter. Using the value 781278TZ, the customer record is identified and added to the newsletter recipients in the shop system.

You must generate and temporarily store the ID for identifying the customer data record in the shop system. This ID is stored in the Optimizely Campaign recipient list.

Initial recipient data transfer and start of the opt-in process

To add a recipient to a recipient list and initiate an opt-in process, the API operation subscribe is requested with the parameters bmRecipientId and bmOptInId. Furthermore, the bmOptinSource field should be specified with the source of the opt-in, for example WebShop/Shoe Store/1.1.2. The customer-id field contains the ID of the customer record.

You can append other fields from the recipient list as parameters and use them to personalize the mailing, for example, salutation, firstname and lastname.

Sample HTTP request:

https://api.campaign.episerver.net/http/form/[AuthorizationCode]/[email protected]&bmOptInId=987654321&customer-id=1234ABCD&salutation=Mr.&firstname=John&lastname=Smith&bmOptinSource=WebShop/ShoeStore/1.1.2

The bmRecipientId parameter is the primary key of the recipient list (usually the email address). The bmOptInId parameter specifies the opt-in process to be triggered. The opt-in process contains the mailing for registration confirmation configured in the client and the URL of the confirmation page to which the recipient is forwarded.

Confirmation link and confirmation page

You must include a confirmation link in the opt-in mailing as field function {Double-Opt-In-Link}. See Opt-in processes.

The field function is converted to an individual confirmation link of the recipient and the customer-id parameter is added: {Double-Opt-In-Link}?customer-id={customer-id}.

The customer-id parameter contains the respective value of the opt-in recipient list.

When the mailing recipient clicks on the confirmation link, the recipient is redirected to the provided confirmation page: https://www.example-shop.com/newsletter/success?customer-id=8122.

You must configure the integration in the shop system in such a way that when the /newsletter/success path is requested, the value of the customer-id parameter is read and used further within the shop system.

You can add further parameters to the confirmation link, as long as your recipient list contains the respective fields. For example, if your recipient list contains the field shop-id, you can add the shop-id parameter to the confirmation link: {Double-Opt-In-Link}?customer-id={customer-id}&shop-id={shop-id}.

Unsubscribe link and confirmation page

While you can create several opt-in processes in one client, only one unsubscribe link is configured per client.

The unsubscribe link is placed in a proper place in the mailing (for example in the footer) so that the recipient can unsubscribe from the newsletter with just one click.

Like the confirmation link, the unsubscribe link first redirects the recipient to Optimizely Campaign to register the unsubscription. The recipient is then redirected to a confirmation page. To add or change the URL of the confirmation page, see Changing the confirmation page URL.

You can also add further parameters to the unsubscribe link if your recipient list contains respective fields: https://www.example.com/newsletter/unsubscribe?customer-id={customer-id}&shop-id={shop-id}.

You have to configure the integration in your shop system in such a way that a request for the path /newsletter/unsubscribe results in a unsubscription of the recipient customer-id. Depending on the system, you can also use the shop-id parameter to address a specific web shop or subpage. Both customer-id and shop-id are already known to the shop system, since both values were written to the recipient list by the shop system when the recipient logged on.

Updating customer data

If a customer changes his or her data in the web shop (for example, address or telephone number), you can update the fields in the recipient list using the HTTP API request updatefields. The email address is used as the primary key for identification (bmRecipientId parameter): https://api.campaign.episerver.net/http/form/[AuthorizationCode]/[email protected]&city=Boston&zip=02108.

With the API request you change the values of the recipient list fields city and zip to Boston and 02108 for the recipient [email protected].

Removing recipients from a recipient list

If a recipient unsubscribes a newsletter from within your web shop, for example via a link or a checkbox, you can register this unsubscription in Optimizely Campaign using the unsubscribe operation: https://api.campaign.episerver.net/http/form/[AuthorizationCode]/[email protected].

The bmRecipientId parameter uniquely identifies the recipient by his or her email address and the API request unsubscribes the recipient from the newsletter. The recipient is entered in a separate unsubscribe list and is no longer contacted. See Unsubscribers.