Skip to main content

Daily Newsletter

First time using Actito's Integration Framework?

Check out the Quick Start before diving into this use case.

Introduction​

This guide walks you through setting up and sending a mass email campaign from your system — ideal for daily or weekly newsletters. You'll cover the full lifecycle:

  • Creating an email campaign from scratch
  • Defining its subject, target audience, HTML content, and personalizations
  • Sending test emails
  • Launching the campaign

Steps overview​

  1. Create an email campaign
  2. Define the subject line
  3. Set the target audience
  4. Define the content and personalizations
  5. Send test emails
  6. Launch the campaign
info

At every step, changes made via the API are immediately visible in the Actito portal, just like edits made directly in the interface.

Prerequisites
  • Read the Concepts section for background on entities and profile tables.
  • Make sure at least one entity and linked profile table exist in your licence (check with your marketer).
  • You'll need an API Key for authentication. If you don't have one, contact our Support Team.

Step 1. Create an email campaign​

Start by creating the campaign and setting its general parameters: name, sender, profile table, supported languages, and sending mode.

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

Example request body:

{
  "contentType": "HTML",
  "encoding": "utf-8",
  "entityOfTarget": "MyEntity",
  "from": "Actito Developer",
  "name": "DailyNewsletter",
  "replyTo": "replies@actito.com",
  "sendingMode": "MASS",
  "supportedLanguages": ["FR"],
  "targetTable": "Contacts"
}

Key parameters in this example:

  • name: DailyNewsletter — unique within the entity, used as an identifier in subsequent calls
  • from: the sender name displayed to recipients
  • targetTable: profiles come from the Contacts table
  • supportedLanguages: targets profiles with FR as their motherLanguage
  • replyTo: where user replies are forwarded

Response (200 OK):

{
  "campaignId": 223
}
Reply-to address

The reply-to address is where Actito forwards replies to your campaign — it is never visible to recipients. If not set, the licence default is used. If no default is configured, replies will not be forwarded.

caution

The / character cannot be used in campaign names.

Step 2. Define the subject line​

Set the subject line that will appear in the email header.

PUT /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/content/subject

Request body (plain text):

Welcome to Actito Daily News

Step 3. Set the target audience​

There are three ways to define the audience for your campaign.

Option A — Filter by language and/or subscription

PUT /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/target
{
  "filterOnLanguage": true,
  "subscription": "Info"
}
Unsubscribe link

To use Actito's standard unsubscribe process, you must link the opt-in to your campaign via this PUT call. The unsubscribe link will then be mapped to the ${unsubscribe} variable in your HTML content.

Option B — Use a saved targeting

Use the same PUT endpoint and add the targetingName field with the name of a targeting previously created in the Actito portal.

{
  "filterOnLanguage": true,
  "subscription": "Info",
  "targetingName": "MyPredefinedTargeting"
}
Saved targeting

It is not currently possible to create complex targetings via the API. For criteria beyond language and subscriptions, create a saved targeting in the Actito portal first, then reference it here.

Option C — Upload a profile list

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

Upload a CSV file with a single column whose header matches a unique attribute of your profile table (e.g. profileId, emailAddress, or any unique key).

Step 4. Define the content and personalizations​

HTML content

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

You can upload the content in two formats:

  • A single HTML file with images referenced via absolute URLs (externally hosted)
  • A ZIP file containing one HTML file per supported language, named with a language suffix (e.g. content_FR.html). HTML files must be at the root of the ZIP.
HTML file tips
  • Maximum ZIP size: 4 MB
  • Recommended maximum image size: 200 kB
  • Use one HTML file and one image folder per language

Link tracking

To track individual links in your HTML content, assign each link a unique name in Actito.

Personalizations

Insert variables directly into your HTML content (and optionally in the subject line or sender name) using a $ prefix — for example, $firstName.

Profile attribute variables are mapped automatically: $firstName will display the firstName attribute of the recipient's profile.

Reserved variables

$unsubscribe and $webversion are reserved and automatically mapped to the unsubscribe and web version links.

For personalizations not coming from the profile table, upload an external CSV file:

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

The CSV must meet the following requirements:

  • At least 2 columns: one for the unique profile key, one for the personalization variable
  • The unique profile key column must be first
  • Column headers must exactly match the profile table key attribute name and personalization variable names

Download an example file.

Step 5. Send test emails​

Before launching, validate your campaign by sending test emails to a set of representative profiles.

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

We recommend sending tests to a "catch-all" address rather than real recipients. If no recipients address is specified, test emails will be sent to the actual profile email addresses.

Example request body:

{
  "key": "contactID",
  "recipients": ["internal.documentalist@actito.com"],
  "values": ["14895", "17125", "18183", "45289"]
}

This sends four emails to internal.documentalist@actito.com — one per profile — each rendered with that profile's personalization data, exactly as it would appear in a real send.

Step 6. Launch the campaign​

Once your campaign is ready, trigger the send:

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

Use the optional sendingMoment query parameter to schedule the send for a specific time. If omitted, the campaign is queued immediately.

Example — schedule for October 1st, 2019:

PUT /email-campaigns/v4/entity/MyEntity/mail/DailyNewsletter/send?sendingMoment=01%2F10%2F2019%2000%3A00%3A00

You're done! You've prepared, configured, tested, and launched a mass email campaign via the API. Check out the other use cases to go further in automating your marketing flows.