Closed Loop interface

To realize complex email marketing campaigns, a bi-directional interface between Episerver Campaign and external systems has been implemented. The external system (i.e., the customer's system) automatically triggers mailings in Episerver Campaign. Action-based mailing data is logged in Episerver Campaign and returned to the external system. This response data can be further processed by the customer within a third system, e.g., in a data warehouse.

The closed loop interface consists of two modules. The import module automatically transfers recipient data (e.g., product recommendations) from your IT system (e.g., data warehouse) to Episerver Campaign and automatically triggers mailings. The response data export module transfers action-based mailing data – such as openings, clicks, responses, unsubscribes, etc. – back to your IT system. Both modules of the interface can be configured separately and used independently of each other. The following picture shows this process in a simplified way without possible exceptions.

A service processes all received data within Episerver Campaign. As soon as you store a file on the server, various jobs are being executed: Recipients are imported, mailings are created, sent and a status notification is sent. The response data export module is responsible for the return channel. This module exports all statistical data to the customer's system. The log data can be integrated into the customer's data warehouse.

Data exchange

The data exchange is realized through a SFTP server set up at Episerver. Recipient data is transferred to that server. Response data is available for download from this same server. Running transfers must have a temporary file name, to avoid incomplete file exchange. The naming conventions are described in the respective paragraphs.

For troubleshooting in the case of incomplete data transfer, see Data transfer troubleshooting.

The above described does not respect the strict separation of clients. All user data can be transferred through one SFTP account. It is possible, though, to set up separate SFTP accounts for each client, if this is necessary for security reasons. Alternatively, it is possible to set up separate sub-directories in one client. In both cases, the recipient data import module must then commit one file per client/directory.

Recipient data transfer

Recipient data can be transferred to Episerver Campaign at any time. The transfer is made to the SFTP server as described above. The name convention of the transferred files must be as follows:

YYYYMMDDHHMMSS_subscribers.csv

The actual recipient file is a CSV file with the following properties:

  • Phrase and field lengths are variable within the limits of the recipient list.
  • A semicolon (;) is used as separator.
  • For line breaks, use line feed.
  • Quotation marks ("") are used as field boundaries. To designate quotation marks within a field, wrap them in quotation marks.
  • The file does not contain declarations regarding columns and field lengths.
  • Empty fields (NULL) remain empty in a data set. The number of field separators must be constant.

Recipient data is processed automatically every 10 minutes. The SFTP server of Episerver Campaign provides log files for download within 30 days after creation.

According to the specifications, all fields of the main recipient list must be committed. Fields that are supposed to not contain any value are committed as empty columns. The existing fields as well as the field sequence are fixed and must not be altered without the consent of both parties.

Personalization and recommendations

Data enhancement of the delivered recipient data is possible to add personalized content, for example product recommendations, to the mailing. One or more fields reserved to a product ID are added to the CSV file containing the recipient data. The product information (e.g. title, description, image-URL) for these recommended products is transferred in a second CSV file. In the mailing, product information is inserted using a placeholder and field functions. Assignation of product id's to recipients is done by the customer.

With a web analysis software, recommendations are available via a CSV file. To each product, other recommended products are assigned. Product information is rendered into the mailing using a special field function, similar to the process described above. No assignation of products to a recipient has to be made, since the web analysis software automatically assigns recommended products according to the initial configuration.

To take advantage of personalized content, Episerver first needs to create a new template for you.

Create source mailings and send mailings

Using Episerver Campaign, a so-called source mailing is created. Placeholders that are referencing a specific field of the recipient list are inserted into the paragraphs of the mailing. Thus, product data and other information can be individually assigned and inserted into the mailing when sending it. If you want to send multiple newsletters or newsletters are sent at the same time, you have to create multiple source mailings. The source mailing is never sent. The system automatically creates a copy of the source mailing and then sends it. The source mailing can then be used again.

As soon as a file containing recipient data is stored on the SFTP server (in the corresponding directory), the mailing is sent. Every ten minutes, a cron job checks this directory for new files. If there is a new file, it is imported into the recipient list of the corresponding client and assigned to the source mailing using the parameter BROADMAIL_ID. There are different ways to add content to a mailing:

  • Directly from the file: The content is imported along with the recipient data in a CSV file. This method is only applicable for texts and hyperlinks.
  • Referenced content: URLs in the imported CSV files are used to reference the content. When sending the mailing, the content is retrieved from the external server of the customer through the content interface. Thus, all types of content (texts, pictures, attachments, hyperlinks) can be added to a mailing.

As soon as the data is imported, the mailing is automatically sent. Every sent mailing gets a unique ID.

Send test email using the closed loop interface

It is possible to send test emails by storing test data on the server instead of real recipient data. The CSV file must have the same structure as the file containing the real recipient data. Every time a test email is sent, a new mailing is created in Episerver Campaign.

Mailings are triggered only by storing a file on the server that is configured for the closed loop interface. It is not possible to send mailings by using the Episerver Campaign user interface.

The source mailing can be customized for different newsletters. If you want to change the source mailing, you have to ensure that the previous mailing was successfully sent. Additionally, you have to ensure that the correct mailing ID of the source mailing is used within the recipient CSV file.

Data transfer troubleshooting

Should there be any problem transferring the data, an email notification is sent. The email address to which notifications are sent can be any email address and will be configured beforehand. An error file is generated and the transfer stopped. The exact behavior of the interface in case of an error can be configured in the course of the implementation process. After the implementation has been completed, this setting can be switched off.

After an error has occurred, the interface must be restarted accordingly. The restart will be made according to the error file. There are two cases:

  • Data import failed
  • Error when mailing was started after data import

Errors during the data transfer are handled by our support, since such errors only can be resolved manually.

Monitoring and sending status

The status of the process after the recipient data has been imported is sent via email and logged into a log file. This assures that all actions within the interface are properly logged and documented by Episerver Campaign.

Structure of the main recipient list

Column name Data type Example Remarks
Email Varchar(255) user@example.com Email address of the user
BROADMAIL_ID Bigint/Long 44018617811 Mailing ID in (BROADMAIL_ID)
WAVE_ID Bigint/Long 46623317811 Identifies the selection/sending wave for unambiguous assignment of user actions. This parameter is optionally set by the external system when importing the recipient data.
Salutation Varchar(255) Field from existing recipient list
First name Varchar(255) Field from existing recipient list
Last name Varchar(255) Field from existing recipient list

The list configuration described above is only a proposal. If necessary, more fields can be added to the list. If additional data are necessary for personalization purposes, tell us beforehand and document them in the interface setup.

Specification of the response data

The response data is generated every day from the log files and available for download at an appointed time via an SFTP server within Episerver Campaign. The files contain the latest data since the last delivery. The files containing the mailing data are available for download within 30 days after starting the mailing. The response data consists of seven CSV files. Basically, each CSV file can be read as a table according to the following ER diagram. More detailed type information can be found in the respective paragraphs for each file.

The file names used in the following sections are examples. The file names can be configured in accordance with your requirements.

Sent mailings

File YYYYMMDD_mailings.csv contains all mailings, which have been sent in the referenced period.

Column name Data type Example Remarks
id Bigint/Long 51106527229 Mailing ID in (BROADMAIL_ID)
mailingGroupId Bigint/Long 44018617811 Client ID in Episerver Campaign
started DateTime 2007-10-24 12:07:55 Start time of the mailing
finished DateTime 2007-10-24 12:09:55 End time of the mailing

Sending Log

The file YYYYMMDD_mailingrecipients.csv contains recipient related data. The sending log refers to the mailings contained in the file YYYYMMDD_mailings.csv.

Column name Data type Example Remarks
mailingId Bigint/Long 51106527229 Mailing ID in Episerver Campaign
userId Varchar(255) user@example.com Email address of the recipient
created DateTime 2007-10-24 12:07:55 Sending date
response.category Varchar(20) Delivery status

Links

The file YYYYMMDD_links.csv contains all links from the mailing.

Data are only available for links with activated link tracking.

Column name Data type Example Remarks

mailingId

Bigint/Long

51106527229

Mailing ID in Episerver Campaignl

id

Bigint/Long

44018617936

Link ID in Episerver Campaign

Name

Varchar(255)

Imprint

Name of the link

url

Varchar(255)

http://www.example.com

Link target (URL)

Clicks

The file YYYYMMDD_clicks.csv contains all clicks in a mailing, within the referenced period, generated by recipients. Clicked links/URLs can be found in the file YYYYMMDD_links.csv.

Column name Data type Example Remarks
mailingId Bigint/Long 51106527229 Mailing ID in Episerver Campaign
userId Varchar(255) user@example.com Email address of the recipient
linkId Bigint/Long 44018617936

Link ID in Episerver Campaign

created DateTime 2007-10-24 12:07:55 Date and time of the click.

There can be multiple clicks from one recipient within one second.

Opens

The file YYYYMMDD_opens.csv contains all opens by recipients for all mailings in the referenced period.

Column name Data type Example Remarks
mailingId Bigint / Long 51106527229 Mailing ID in Episerver Campaign
userId Varchar(255) user@example.com Email address of the recipient
created DateTime 2007-10-24 12:07:55

Time and date when the mailing was opened by a recipient.

One recipient can open a mailing several times. In this case, each opening generates a singular data set.

Unsubscribes

The file YYYYMMDD_unsubscribes.csv contains all unsubscribes from recipients within the referenced period.

Column name Data type Example Remarks
mailingId Bigint/Long 51106527229 Mailing ID in Episerver Campaign
userId Varchar(255) user@example.com Email address of the recipient
created DateTime 2007-10-24 12:07:55 Date and time of the unsubscribe

Responses

The file YYYYMMDD_responses.csv contains all emails that have been returned to the sender address from any user within the referenced period.

Column name Data type Example Remarks
mailingId Bigint/Long 51106527229 Mailing ID in Episerver Campaign.
mailingToUserId Varchar(255) 25951836752 Encoded assignment of the recipient.
userId Varchar(255) user@example.com Email address of the recipient.
category Varchar(20)
  • unknown – The recipient sent a response to the mailing.
  • bounce – Soft bounce.
  • temporary_bounce – Soft bounce.
  • fatal_bounce – Hard bounce.
  • autoresponder – Autoresponder.
Delivery status.
created DateTime 2007-10-24 12:07:55 Date and time of the response.

Installation and fees

The installation of a closed loop interface is subject to a one-time expense. For operation and maintenance, a monthly service fee is charged. Prices vary due to the configuration of the interface (uni- or bi-directional). For detailed information and calculation, ask customer support.

Since the response data consists of non-anonymized action-based data, you will have to indemnify and hold us harmless in advance from any potential liabilities and third-party claims which may result from making this functionality available to you.

back to top Episerver image




Episerver | Updated: 2019-03-06 | Send feedback to us