Setting up an e-mail campaign

The first step of the creation of your campaign will consist in creating it by defining its general parameters.

To do so, you will need to use the operation POST/entity/{e}/mail

First of all, specify the entity on which this campaign will be created.

Next, the body of the request will need to contain the general parameters as JSON code:

• "contentType": the default and only value is “HTML”. The creation of an e-mail campaign through API necessarily entails defining its content by importing a HTML file.

• "encoding": the way the mail is encoded. For example, “UTF-8” or “ISO-8859-15”.

• "entityOfTarget": entity of the profile table on which the e-mail is defined.

• "from": sender of the mail, as it will appear in the e-mail header.

• "goalTracking": if you have set up goals, defining this parameter as "true" will allows you to track goals triggered by that campaign. You therefore have to specify the id of this goal in the "id" parameter.

• "name": name of the campaign. It will be the campaign name that will appear in the ACTITO. It can also be used as technical name in order to identify the campaign when making further calls.

• "replyTo": when sending out an e-mail campaign, it is possible to indicate a reply-to address to which user replies will be forwarded. If this optional parameter is not specified, the default address in your license preferences will be used.

• "sendingGroups" : this optional parameter can be used to list the sending groups to which the e-mail belongs. An e-mail is always assigned to a default sending group that resumes all e-mails from the same entity and the same profile database.

• "supportedLanguages": the languages in which you want to send your campaign. At this stage, it is only possible to send a campaign in one language at once.

• "targetTable": the name of the profile table targeted by your campaign.

Example of request including JSON code and its response: (Download this example)

The response to the request will be the auto-generated technical id, which will be used to identify the campaign while making further calls.

Defining the subject of an e-mail

After creating the basis of your campaign, you need to define its subject, such as it will appear in the header of your e-mail.

To do so, you can use the operation PUT/entity/{e}/mail{m}/content/subject

The parameters provided for this operation are:

• the entity on which the campaign is stored

• the id of the e-mail campaign: it can be its auto-generated id or the technical name that you defined at the previous step.

• the subject of your e-mail: please note that it is not possible to insert a customization in this subject.

Example of a request and its response: (Download this example)

The response to this request will be the auto-generated campaign id.

Defining the target of an e-mail

It is not possible to directly use the targeting module through webservices. However, it is possible to set up filters based on subscriptions and languages, as well as using a saved targeting.

You also have the possibility to define the targeting by importing a list of profiles identified by a unique attribute of your database.

As any campaign created through API is directly available in ACTITO, you retain the possibility to target your profiles via the targeting module of the interface.

Defining the content of your e-mail

The content of your e-mail can be defined directly through webservices. To this purpose, it mustbe set up as HTML content.

To define the content of your e-mail, you need to use the operation POST/entity/{e}/mail{m}/content/body

You will need to define the following parameters:

• the entity on which the campaign is stored

• the e-mail campaign id (technical id or technical name)

• "charset": this is the format of the imported file (for example, UTF-8)

• "inputFile": this is the ZIP file containing the HTML used to define your content

  

There are two possibles format for the imported content file:

• a single HTML file containing the images in absolute (meaning that the images are hosted on another server)

• a ZIP file, containing one or more HTML files depending on the number of languages defined for the e-mail campaign. In the case of a multilingual mailing, a suffix must be added to these files: ‘_’ followed by the language code in two letters (for example: '_FR'). The HTML files must be found at the root of the ZIP file.

Setting up a customization file

Only customizations based on attributes will be automatically mapped at their creation. For external variables, it will be necessary to import an external customization file.

This file will also be based on profile attributes, but it will let associate external data to them. For each specific value of an attribute, you will be able to associate a customization value. This is an individual customization, as the filed must be based on a key attribute. It will allow you to associate a unique value to each profile (for example, a unique discount code for each "customerId" attribute).

The following parameters must be provided:

• the entity on which the campaign is stored

• the e-mail campaign id (technical id or technical name)

• "key": state the name of the unique attribute which will be used a key to identify profiles

• the format of the customization file: it can be a CSV file (in which case you need to specify the separator) but also an Excel file (.xls or .xlsx)

• "charset": this is the format of the imported file (for example, UTF-8)

• "inputFile" this is the zipped CSV file containing your customization file

Your file must fit some constraints when it comes to its format:

You file must contain at least 2 columns, but it can contain more if several variables are based on the same key attribute.

The first column must contain the values for the key attributes, which will link the customizations to each profile. The following columns must contains the values for these customizations.

The column header must exactly match the technical name of the key attribute and the name of the customization variables. For example, if you chose the 'customerId' attribute as key and included 2 customizations in your HTML ($code and $variable), the header of your columns should be: 'customerId;code;variable'.

The response to this request will be the auto-generated technical id of the campaign.

Sending test e-mails

In order to check out the parameters and the content of your campaign, it is possible to send out test e-mails through the ACTITO APIs.

You will have the possibility to choose a group of profiles whose personal information will be used to test the customization of the test e-mail. You can however choose not to really send any e-mail to theses profiles, but to select one or more internal adresses which will receive the test. This option is highly advised.

To do so, you can use the operation POST/entity/{e}/mail{m}/test

You will have to indicate the entity on which the campaign is stored, the campaign id, then the test data as JSON code in the 'testInformation' parameter:

• "key": this is the unique profile attribute used as a key to identify the profiles on which the test e-mails are based.

• "values": you can provide the values specific to each test profile for the chosen key attribute.

• "recipients": this allows you to specify a list of e-mails addresses which will receive the tests. These addresses do not necessarily have to appear in the database. If you do not specify any address in this parameters, the test profiles will the receive the test-e-mails for real.

Example of call for sending tests to an internal address on the basis of 4 profiles identified by a client number: (Download this example)

The response to this request will be the auto-generated technical id of the campaign.

Sending the e-mail campaign

Once your e-mail is ready, meaning that you defined its parameters, chose the target, designed the message, set up customization, and that you are pleased with your tests, you can proceed with sending your e-mail.

This is possible through the operation PUT/entity{e}/mail{m}/send

You will need to provide the entity on which the campaign is stored as well as the campaign id (auto-generated id or technical name). In doing so, the e-mail will be sent immediately.

Two optional query parameters allow you to modify the sending behaviour:

• "sendingMoment": this allows you to plan your sending at a future date of your choice. For example, you need to use the following format: 22/05/2019 15:00:00

• "onlyOneEmail": if the e-mail address is not a unique attribute in your database, the later may contain several profiles with the same e-mail address. Setting up this parameter as "true" will ensure that only one e-mail will be sent per e-mail address.

Example of a request and its response for a planned e-mail sending: (Download this example)

The response to this request will be the auto-generated technical id of the campaign.

Activating a continuous campaign

A continuous sending should be created beforehands, exactly as explained in the previous operations. After that, it must be activated.

This is done through the operation PUT/entity/{e}/mail/{m}/activate

The parameters needed are the entity on which the campaign is stored and the campaign id.

You will obtain the technical id of the sending as response and the campaign will be henceforth activated.

Contacting a profile with a continuous sending

When a profile fits the conditions determined by the purpose of your continuous sending, the later can be triggered through the operation POST/entity/{e}/mail/{p}/profile{p}

You will need to specify the following parameters:

• the entity on which the campaign is stored

• the campaign id (auto-generated id or technical name)

• the id of the targeted profile (profileId or "keyAttribute=value" pair)

• variables:

Obtaining the general information about a campaign

You can obtain the information about a particular campaign through the operation GET/entity/{e}/mail{m}

By specifying the entity and the id of the targeted campaign, you will obtain the general parameters of the targeted campaign (such as the targeted profile table, its entity, the campaign language,...)

Example of a request and its response: (Téléchargez cet exemple)

Obtaining the general information of campaigns based on criteria

You can retrieve the information about one or more campaigns with the help of search criteria through the operation GET/entity{e}/mail

In addition to the entity, the following parameters can be used as filters:

• "name": you can search on the basis of campaign names. By inserting an asterisk at the front or at the end of the search term, you can search for every campaign beginning or ending in this term.

• "type": you can choose to only target mass sendings or continuous sendings.

• "dateFilter": this is a date filter based on the creation or update moment, with a logical operator and the chosen date.

You will obtain a response similar to the previous method, except that you may obtain several campaigns, depending on your search criteria.

Retrieving the subject of the campaign

You can obtain the subject of a campaign through the operation GET/entity{e}/mail{m}/content/subject by using the entity and the e-mail id as parameters

The response obtained will be the e-mail subject as a string of characters.

Retrieving the content of a campaign

If you want to use the content of a previous e-mail for your next campaign, you can retrieve its HTML content, whether it was defined in the interface or through API.

To do so, you can use the method GET/entity/{e}/mail{m}/content/body by using the entity and the id of the e-mail as parameters.

You will obtained the HTML content directly in the response body.

Retrieving the customization file of a campaign

You can retrieve the customization file of a campaign through the operation GET/entity/{e}/mail{m}/personalization by using the entity and the e-mail id as parameters.

To access the file, click on the "Request URL"

This operation is available for both e-mail campaigns created through API or via the ACTITO interface, but only for customizations set up with a customization external file.