Loading...
Area: Episerver Campaign

Getting started

Recommendations [hide]

This topic describes how to set up the REST API and send requests to retrieve data from and send data to Episerver Campaign.

In this topic

Client setup

To set up the REST API in your client, contact customer support.

Provide a separate email address that you do not yet use for Episerver Campaign. This address must use the same domain as your Campaign user login and should not be personalized, for example api-user@company.com.

You should also have access to the inbox of this address, as Episerver will send an activation mail. Using that email address, customer support will set up your API user.

Note: Do not log in to the Episerver Campaign front end by using your API user credentials. API users only have access to services and operations needed for API purposes.

Authentication

The authentication is done via HTTP Basic Authentication with the API user (email address) and API password that customer support sets up for you. Your credentials must be Base64-encoded. The endocded API key is required for all API requests. See also: Requests.

Tip: To encode User:Password and create the API key, you can use online encoding tools, such as www.base64encode.net.

Authorization in Swagger

To use the Try it out feature and send REST API requests in Swagger, do the following:

  1. Click Authorize.
  2. Enter your API key in the value field. The API key consists of the Basic method and the Base64 encoded User:Password.

  3. Click Authorize.

Information regarding general use

The REST API only accepts HTTPS requests. For performance reasons, there is a limit of 25 parallel REST API connections per client.

Tip: Episerver Campaign supports Transport Layer Security (TLS) version 1.2 and higher to encrypt data transmission via API requests.

The base URL for all requests is as follows:

https://api.campaign.episerver.net/rest/{clientId}/{component}/{path}/{parameters}

  • clientId. The ID of your Episerver Campaign client. See also: Finding IDs.
  • component. The Episerver Campaign feature or resource you want to work with. For example, /recipients/, /transactionalmail/, /smartcampaigns/.
  • path. The specific path or part of the resource you want to work with. For example, recipients/{recipientListId}.
  • parameters. The query parameters for modifying the request. Query parameters always begin with a question mark and are combined with an ampersand. For example, ?sort=created&limit=50.

Finding IDs

After customer support has set up an API client, you can find the client ID in Episerver Campaign under Administration > API overview > REST API. See also API overview in the Episerver User Guide.

API overview

Tip: Campaign ID, mailing ID, confirmation ID and so on are documented in the corresponding list in Episerver Campaign.

Data formats

The following formatting rules apply:

Value Format Example
int/long Decimal notation without additional symbols 10000 or 5
float/double Decimal notation separated by a period (.) 12345.67 or 29.99
date/time ISO-8601: YYYY-MM-DDTHH: MM: SSZ 2001-08-21T18:52:05+02:00 (+02:00 stands for CEST)

Requests

A REST API request consists of the following parts:

  • Request method. There are different HTTP methods, such as GET, POST, PUT and DELETE. For example, use the GET method to retrieve data, and the POST method to send data.
  • Request URL. The URL of the requested resource including IDs and parameters. For example,
    https://api.campaign.episerver.net/rest/123456789/recipientlists?sort=created.
  • Request header. For transferring additional information such as authentication credentials or resource information. For example, Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv= to authorize via Basic Authentication. See Responses.
  • Request body. For transferring data via POST, PUT, PATCH or DELETE requests. For example, recipientId=user@example.com.

To send a request and test the Episerver Campaign REST API, you can use the Swagger Try it out feature. You can also use REST API clients, such as curl or Postman.

Requests in curl

Curl is a widely used command-line tool for transferring data and sending REST API requests.

GET request

The following example retrieves information about all recipient lists in a client. The retrieved data is in JSON format and sorted by creation date.

curl -X GET "https://api.campaign.episerver.net/rest/123456789/recipientlists?sort=created " -H  "accept: application/json" -H  "Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv="

POST request

The following example adds a recipient to a recipient list using the ID of the specific recipient list. The ID (email address) of the new recipient is sent via the request body.

curl -X POST "https://api.campaign.episerver.net/rest/123456789/recipients/987654321" -H  "accept: application/json" -H  "Authorization: BASIC k783r3fjn989dhnfjjdr83dgds1383NDfv=" -H  "Content-Type: application/x-www-form-urlencoded" -d "address=&optinProcessId=&data=&returnOptInMailId=&recipientId=user%40example.com"

Responses

A REST API response consists of the response header and the response body. The response header provides information about the response, such as content type, server or creation date and time. The response body is usually a JSON file that consists of status codes and parameter-value pairs of the retrieved data.

The following example shows a JSON response body for a GET request to retrieve information about a recipient:

{
  "id": "user@example.com",
  "created": "2020-09-28T18:18:15+02:00",
  "modified": "2020-09-28T18:18:15+02:00",
  "links": [
    {
      "rel": "self",
      "href": "https://api.campaign.episerver.net/rest/123456789/recipients/987654321/user@example.com"
    }
  ]
}

Status codes

Each response provides status codes and status descriptions, whether the request was successful. You can find all possible status codes for each request in the Swagger REST API documentation.

Success status codes

Usually, GET requests return a 200 status code if the data is successfully retrieved. POST requests usually return a 201 status code if new data is successfully created.

Tip: Even if you get a success status code, the response may contain errors, failures or warnings. Therefore, always check the response.

The following list shows sample success status codes. Depending on the request, the description may differ.

Success status code Description
200 The recipient was retrieved successfully.
201 The recipient was added successfully.
202 The recipient history was deleted successfully.

Error status codes

The following list shows sample error status codes. Depending on the request, the description may differ.

Error status code Description
400 Recipient ID update is not possible because of a general error.
404 The recipient could not be found. Ensure that the required parameters such as 'recipientId' and 'recipientListId' are correct and the recipient exists.
406 The tracking opt-out is not activated for this client. Ensure that the 'clientId' is correct and the required feature is enabled in the indicated client.
409 The coupon block is not assigned to the indicated client. Ensure that 'clientId' and 'couponBlockId' are correct and that the 'couponBlockId' is assigned to the indicated client.

Related topics

Do you find this information helpful? Please log in to provide feedback.

Last updated: Oct 08, 2020

Recommendations [hide]