Setting up a newsletter subscription via REST API
To expand your database of email recipients and attract new potential customers, newsletter subscriptions are essential. I recommend the double opt-in method, which ensures that the recipient really wants to receive promotional emails.
This procedure works like this: When website visitors fill out the subscription form on your website and submit their contact information, they receive an email and are prompted to confirm the subscription by clicking the double opt-in link.
To set up the subscription using the Episerver Campaign REST API, perform the following steps:
- Create an opt-in recipient list
- Create an opt-in process
- Set up the subscription form
- Set up the REST API request
Creating an opt-in recipient list
To create an opt-in recipient list, you can use the recipient list management feature in Episerver Campaign. If you do not have enabled this feature in your client, you can also request an opt-in recipient list from customer support.
For an opt-in recipient list, at least the recipient list field "Email" must be assigned. This field is used for the recipient ID. Also, set the list type to "Opt-in".
Creating an opt-in process
To create an opt-in process, you can use the opt-in process self-service in Episerver Campaign. When creating, you specify the opt-in recipient list you created earlier, and add the double opt-in link to the opt-in email.
Setting up the subscription form
Set up a form on your website for collecting the website visitor’s contact data. Create at least an input field for the email address. The more recipient data you collect, the more precisely you can individualize and personalize newsletters. For example, you can add additional fields for the first name, last name, and salutation.
Each input field in the form must have a corresponding recipient list field into which the data is imported. For more information and tips on creating subscription forms, see the Episerver User Guide.
The following example shows a basic HTML subscription form:
<html lang="en">
<head>
<title>Newsletter subscription</title>
</head>
<body>
<h1 style="font-family: Arial, sans-serif">Newsletter subscription</h1>
<p style="font-family: Arial, sans-serif">To stay up to date on special offers and promotions, subscribe now!</p>
<form action="" method="post">
<input style="font-family: Arial, sans-serif" type="text" name="email" placeholder="Enter your email address" size="30"/>
<input style="font-family: Arial, sans-serif" type="submit" name="subscribe" value="Subscribe"/>
</form>
</body>
</html>Setting up the REST API request
To use the REST API, set up your client first. Use the POST/{clientId}/recipients/{recipientListId} operation to add a new recipient to the opt-in recipient list. You can use the "Try it out" feature of our resource documentation to create and test the request.
You need the following information for the request:
- Client ID. ID of the client the REST API is set up for.
- Recipient ID. Email address that the website visitor enters into the form.
- Recipient list ID. ID of the opt-in recipient list that is used for the double opt-in process.
- Opt-in process ID. ID of the double opt-in process.
Tip: You can find the IDs in Episerver Campaign under Administration > API overview. To retrieve the recipient list ID and the opt-in process ID, you can also use the GET/{clientId}/recipientlists and GET/{clientId}/optinprocesses operation.
If you have additional fields, such as last name or salutation, add the corresponding parameters to the request. The following curl request only uses the email address, and the Base64-encoded User:Password as authentication:
curl -X POST "https://api.campaign.episerver.net/rest/123456789/recipients/987654321" -H "Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv=" -d "optinProcessId=12345654321" -d "recipientId={emailaddress}"Connect the API request with the subscription form, for example in a PHP file. Instead of using the Base64-encoded User:Password, add your API user and password directly into the PHP file.
The following PHP example only shows a basic implementation. Also, make sure your form is secured from misuse by using a CAPTCHA, IP blocking or similar measures according to your usage scenario.
<?php
if(isset($_REQUEST['subscribe'])){
$user = 'user@example.com'; // API user name, usually your email address
$password = 'password1234'; // password of your API user
$clientId = 123456789; // ID of the client the REST API is set up for
$recipientlistId = 987654321; // ID of the opt-in recipient list that is used for the double opt-in process
$optinProcessId = 12345654321; // ID of the double opt-in process
$URL='https://api.broadmail.de/rest/'.$clientId.'/recipients/'.$recipientlistId;
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL,$URL);
curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($curl, CURLOPT_TIMEOUT, 30); //time out after 30 seconds
curl_setopt($curl, CURLOPT_RETURNTRANSFER,1);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, "$user:$password");
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS,"optinProcessId=”.$optinProcessId.”&recipientId=".$_REQUEST['email']."");
$result = curl_exec ($curl);
print_r($result);
}
else
{
?>
<html lang="en">
<head>
<title>Newsletter subscription</title>
</head>
<body>
<h1 style="font-family: Arial, sans-serif">Newsletter subscription</h1>
<p style="font-family: Arial, sans-serif">To stay up to date on special offers and promotions, subscribe now!</p>
<form action="" method="post">
<input style="font-family: Arial, sans-serif" type="text" name="email" placeholder="Enter your email address" size="30"/>
<input style="font-family: Arial, sans-serif" type="submit" name="subscribe" value="Subscribe"/>
</form>
</body>
</html>
<?php
}
?>Now, your newsletter subscription is complete. Publish the page with the subscription form on your website. When website visitors enter their email address and click on the "Subscribe" button, the double opt-in process is initiated and the visitors become mailing recipients.
Besides newsletter subscriptions, unsubscribe options are also important for email marketing. For more information, see my new blog post Working with newsletter unsubscribes.