Views: 934
Number of votes: 2
Average rating:

Creating a Smart Campaign and mailing via REST API

Instead of using the front end, you can use the features and functionalities in Episerver Campaign remotely via REST API. For example, you can create a Smart Campaign including its mailings. In this blog post, I like to show you a basic example on how to do so.

To create and send a mailing campaign in Smart Campaigns (Episerver Campaign's marketing tool for sending out one-shot-campaigns), perform the following steps:

  1. Create a Smart Campaign
  2. Create a mailing and connect the nodes
  3. Start the campaign

Creating a Smart Campaign

To create a Smart Campaign, use the POST/{clientId}/smartcampaigns operation. You need the following information:

  • Client ID. The ID of the client the REST API is set up for. You can find the client ID in Episerver Campaign under Administration > API overview > REST API.
  • Recipient list ID. The ID of the recipient list you want to use for your campaign. Use the GET​/{clientId}​/recipientlists operation to retrieve all recipient list IDs of your client. You can also find the recipient list IDs in the Episerver Campaign start menu under Administration > API overview > Recipient lists.
    Tip: Use a test recipient list to send a test mailing before the actual dispatch. You can also use the POST/{clientId}​/smartcampaigns​/{campaignId}​/messages​/{mailingId}​/test operation after you have created the mailing and connected the nodes.
  • Name. Specify a name for the campaign, such as Test campaign.

The request in curl looks as follows:

curl -X POST "https://api.campaign.episerver.net/rest/123456789/smartcampaigns" -H "Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv=" -d "recipientListIds=9876543210" -d "name=Test%20campaign"

In the response body of the request, you can find information about the created campaign, such as campaign ID, name, status, and creation date.

Creating a mailing and connecting the nodes

The created campaign is incomplete and requires further editing. Use the POST/{clientId}/smartcampaigns/{campaignId}/messages operation to create a new message node with the actual mailing and connect it with the recipients node that contains the recipient list.

You need the following information:

  • Client ID
  • Campaign ID. ID of the created Smart Campaign. To get the campaign ID, you can use the GET​/{clientId}​/smartcampaigns operation or go to the Episerver Campaign start menu > Campaigns > Smart Campaigns.
  • Media type. Media type of the mailing, for example email.
  • Sender address. Email address of the mailing sender.
  • Predecessor node ID. The ID of the recipients node. To retrieve the node ID, you can use the GET​/{clientId}​/smartcampaigns​/{campaignId} operation.

You also need to specify further parameters, such as mailing name, mailing subject, media type, and set the "resetReplyToAddress" parameter to "true". When creating the mailing, you can only add plain text as mailing content. I will show you how to update the mailing with HTML or multipart content in a later blog post.

The request in curl looks as follows:

curl -X POST "https://api.campaign.episerver.net/rest/123456789/smartcampaigns/12345654321/messages" -H "Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv=" -d "senderName=John%20Smith" -d "predecessorNodeId=2" -d "name=Test%20mail" -d "subject=Test%20newsletter" -d "replyToName=John%20Smith" -d "content=This%20is%20the%20mailing%20content." -d "resetReplyToAddress=true" -d "mediaType=email" -d "senderAddress=user%40example.com"

You cannot divide the mailing content into individual content paragraphs via REST API. To do so, create the mailing in the Episerver Campaign front end by using the Template Kit. This also lets you personalize each content paragraph via target groups.

Starting the campaign

To send out the mailing, activate and start the campaign. Use the following operations:

Tip: After sending out the campaign, you can retrieve a report with information about opens, clicks, unsubscribes and bounces by using the GET​/{clientId}​/smartcampaigns​/{campaignId}​/report operation.
Jan 15, 2021

Philipp Gaska
( By Philipp Gaska, 6/21/2021 9:30:58 AM)

If you create a mailing via REST API, you can only add plain text content. See the new blog post Updating mailing content via REST API to learn how to update the mailing with HTML or multipart content.

Please login to comment.