Daily Newsletter

First time using ACTITO's Integration Framework?

Check out the "Quick start" before going into this case!

Introduction

If you aim to load and launch your daily (or weekly) newsletters from you system, reading what follows is a must!

You'll find here explained how to set up and send your mass e-mail campaign:

Create an e-mail campaign from scratch
Set up its HTML content, subject, targeting and personalizations
Send tests
Send the campaign

Step by Step

Set up your e-mail campaign
Define the subject line
Update its target
Define its content and personalizations
Send test e-mails
Shoot the real the e-mail campaign

info

Note that at any step of this process, your modifications are visible in ACTITO portal as any other campaign edited within the portal.

Prerequisites

Take a look at our concepts section for few explanations on entities and profile tables in ACTITO.
Make sure some entities and linked profile tables exist in your licence (check with your marketeer).
If you don't already have a webservice user for the API authentication, ask our Support Team.

Step 1. Create an e-mail campaign

The first step of the set up of your campaign will consist in creating it by providing its general parameters such as a unique name, the profile table which the target come from and other common settings.

To do so, assuming you have an ACTITO entity named MyEntity, you will need to use the operation:

POST /email-campaigns/v4/entity/MyEntity/mail

First of all, specify the entity on which this campaign will be created. (Read ACTITO Concepts section to learn what entity is.)

The following example creates a new DailyNewsletter campaign in MyEntity entity:

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA" -d "{
	\"contentType\": \"HTML\",
	\"encoding\": \"utf-8\",
	\"entityOfTarget\": \"MyEntity\",
	\"from\": \"ACTITO Developer\",
	\"name\": \"DailyNewsletter\",
	\"replyTo\": \"replies@actito.com\",
	\"sendingMode\": \"MASS\",
	\"supportedLanguages\": [
		\"FR\"
	],
	\"targetTable\": \"Contacts\"
}" "https://api.actito.com/email-campaigns/v4/entity/MyEntity/mail"

The following parameters were chosen in this example:

campaign name DailyNewsletter (as the name is unique by entity, it can be used as an identifier)
the sender name is set to ACTITO Developer
the file with the content must have HTML UTF-8 format
the recipients come from the profile table named Contacts
the campaign will be sent to french profiles (those who have FR value in the motherLanguage standard attribute, see ACTITO Concepts to understand it in details)
the reply-to address is replies@actito.com

If everything is OK, you should receive a 200 OK http response with a body that contains the created campaign id like follows:

{
  "campaignId": 223
}

Reply-to address

The reply-to address is the e-mail address where ACTITO will redirect all the users' answers to your mass campaign. This e-mail address will never shows up to the recipients of your campaign, but their replies will be forwarded to that reply-to address.
If you do not set any, the default address of your license will be used.
If no default address is define in your license, answers won't be forwarded.

caution

The '/ ' character cannot be used in campaign names.

Step 2. Define the subject line

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 /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/content/subject

In the below example the "Welcome to Actito Daily News" subject is set in the previously created campaign :

curl -X PUT
--header "Content-Type: application/json"
--header "Accept: application/json"
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA" -d "Welcome to Actito Daily News"
"https://api.actito.com/email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/content/subject"

Step 3. Update its target

There are three possibilities to define the target of an e-mail campaign:

Set up simple filters based on subscriptions and languages.
Reference a saved targeting (learn how to create it in ACTITO documentation).
Upload a flat file containing the list of profiles from the profile table linked to the campaign (referenced by using one of the table unique keys).

Note that as any campaign created through the API is directly available in ACTITO portal, remains the possibility define more complex targets via the targeting module of the portal.

Saved targeting

It is as for now not possible to create the targeting through our APIs using other criteria than language, subscriptions and the list of unique ID's. To use more complex targeting, you must first create a "saved targeting" in ACTITO portal, and then reference it in your API triggered campaign.

Defining the target based on the language or the subscription

To do so, call the following operation:

PUT /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/target

And provide a json body with filterOnLanguage and subscription attributes.

So that shows this curl example:

curl -X PUT
    --header "Content-Type: application/json"
    --header "Accept: application/json"
    --header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA" -d "Welcome to Actito Daily News"
    -d "{
  \"filterOnLanguage\": true,
  \"subscription\": \"Info\"
}" "https://apitest.actito.com/email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/target"

Unsubscribe link is mandatory

If you wish to use ACTITO standard unsubscribe process, you must link the opt-in to your campaign via PUT /entity/{e}/mail{m}/target call.
The unsubscribe link will then be mapped to the ${unsubscribe} personalization variable in your HTML content.

Defining the target based on a "saved targeting"

Use the same PUT call as above but fill the targetingName attribute value with the name of the targeting you previously created in ACTITO Portal.

curl -X PUT
    --header "Content-Type: application/json"
    --header "Accept: application/json"
    --header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA" -d "Welcome to Actito Daily News"
    -d "{
  \"filterOnLanguage\": true,
  \"subscription\": \"Info\",
  \"targetingName\" : \"MyPredefinedTargeting\"
}" "https://apitest.actito.com/email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/target"

Defining the target based on an comprehensive list

In order to define your target by importing a file containing a list of profiles, you may use the operation:

POST /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/target/list

The list of profiles you want to target must be a CSV flat file containing a single column whom header maps a unique attribute of your profile table (ex : profileId, client number, e-mail address, or any unique attribute).

Step 4. Define the content and personalizations

HTML content

The HTML content of your e-mail can be defined directly through the API.

To do so, you may to use the operation:

POST /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/content/body

There are two possibles format for the imported content file :

a single HTML file referencing images with absolute links (meaning that the images are hosted on an external server)
a ZIP file, containing one HTML file (or many, depending on the number of supported languages defined for the campaign).
In the case of a multilingual campaign, a suffix must be added to these files: ‘_’ followed by the language code in two letters (for example: '_FR').
The HTML files must be located at the root of the ZIP file.

Link tracking

ACTITO enables you to track the links present in your HTML content. To allow this tracking, you must define a unique name for each link you want to track individually.

Personalizations

It is possible (and advized) to use personalization in your HTML content (note that it is possible to do so in the subject line and/or sender name too).
To do so, you should insert variables anywhere you want a personalization to appear in your HTML. A variable is defined by a variable name prefixed by a $. Ex : $mypersonalization is a variable name that should then be mapped to a specific personalization.

NB : personalizations defined through APIs can only be mapped to profile attributes or external values.

For profile attributes personalizations (see ACTITO concepts), an automatic mapping will link variables whose name matches an existing attribute in the profile table.

For example, $firstName personalization will automatically display the content of the firstName attribute of the recipient profile.

External personalizations, not coming from the profile table data, can be provided by upload an external file to the campaign.

You can do that by calling:

POST /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/personalization

The provided file must be a CSV flat file in which each line contains the personalization for a single recipient profile. The file must include a column that contains the unique key value that will be used to match personalization to the recipient profile.

Each external personalization should then be mapped to one of the column of the uploaded file.

This file must fit some other constraints:

You file must contain at least 2 columns (one to match the recipient profile, one for the variable).
The column with unique profile keys must be the first column of the file.
The column headers must exactly match the technical names of the profile table key attribute and personalization variable names.

Download an example file.

Unsubscribe and web version links

$unsubscribe and $webversion are reserved personalization variables that will be mapped to the Unsubscribe and web version links.

HTML file format tips

It is advised to use one HTML file and one image folder per language. The maximum weight of the ZIP is 4 MB. We advise that each image should not weight over 200kB.

Step 5. Send 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 ACTITO APIs.

You will have to choose a group of profiles whose personal information are representative of the personalizations you want to check. It is highly advised that you send the test e-mails for those profiles to a "catch all" list of recipient e-mail addresses.

To do so, you can use the operation

POST /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/test

The addresses indicated in "recipients" parameters 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.

For example, if you make the below call ...

curl -X POST
    --header "Content-Type: application/json"
    --header "Accept: application/json"
    --header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA"
    -d "{
    \"key\": \"contactID\",
    \"recipients\": [
        \"internal.documentalist@actito.com\"
    ],
    \"values\": [
        \"14895\",
        \"17125\",
        \"18183\",
        \"45289\"
    ]
}" "https://api.actito.com/email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/test"

... four e-mails will be sent to the e-mail "internal.documentalist@actito.com", one for every profile whose contactID is 14895, 17125, 18183 or 45289.

Each e-mail will display the content with the personalizations corresponding to the targeted profile as if it was a real e-mail aimed at him/her.

Step 6. Shoot the full real e-mail campaign

Once your campaign is ready, you can proceed with sending your e-mail.

To do that, call the operation:

PUT /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/send

Note that you can provide a sendingMoment query parameter to schedule the launch later. If not, e-mail is queued immediately.

In the following example the campaign we created in previous steps will be sent on October, 1st 2019 at 8PM.

curl -X PUT
    --header "Content-Type: application/json"
    --header "Accept: application/json"
    --header "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0IiwiaWF0IjoxNTg2ODY1MjE1LCJpc3MiOiJhY3RpdG8iLCJleHAiOjE1ODY4NjYxMTUsImxpY2VuY2VJZCI6MTI3NDAsImFjY291bnRJZCI6MTIsInBvbCI6Im1haW5Qb2xpY3lBcGkiLCJzdWIiOiI2ZWY3YjZmYS0wYTc1LTQ1YTYtYmE5My1iZGY5MmUyZjg3NDAifQ.umizXm0TueN6jRkMCaz9AnQP30qNxud5XIxnZiPzz24L8Aon7WKeJ8_49xcjsTe_v13nv4AI9991Mw_k9bvQffT__eikkv9UMmZ22wvQr5UxCH5Y-NkxFRctEGLjmkEdFFe2EuOkF1GjsIetPrJgY-_L6bpoa3G0o69IWavBIFowQtw_q0FOPaZ_JtBLiDiFH59IM5s4-8S-QAhGkGgjOhTzqBTyDBGj8cqnhvr9eFwgoxGSAZ1QLGU5yTRyIJm8Uaq97M5UhKn98ixK4oQhQvVKwW9MDgGyf0jLFLEFO7l9kyFON34OsxiTyK58U_OFJzehgxqRokBE3wXWo9rKEA"
    "https://api.actito.com/email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/send?sendingMoment=01%2F10%2F2019%2000%3A00%3A00"

That's all!

You are now done with preparing, feeding, testing and launching mass e-mail campaigns!
Check our other use cases to go further in automating your marketing flows!

Introduction​

Step by Step​

Step 1. Create an e-mail campaign​

Step 2. Define the subject line​

Step 3. Update its target​

Step 4. Define the content and personalizations​

Step 5. Send test e-mails​

Step 6. Shoot the full real e-mail campaign​