Simple campaign creation

Campaigns in mindbaz

In Mindbaz, you can create 2 types of campaigns:

• simple campaigns
• Dynamic campaigns

It is important to understand this concept before going further in the creation of campaigns.

A simple campaign cannot be modified after the first sending. It is generally only scheduled once. This type of campaign is often used to send advertising content.

In contrast, a dynamic campaign can be modified after the first sending. It can easily be scheduled several times with different content. In concrete terms, as soon as a dynamic campaign is sent out, a "picture" of the campaign is made in the form of a simple campaign. And it is this picture that is sent. In this way, the campaign remains editable for the next sending.

To find out more about creating a campaign from the interface, click here.

Steps to follow before creating your campaign

1. import your subscribers

Your database in Mindbaz must be up to date in order to capture new subscribers and not solicit unsubscribers. To do this, you can connect your subscription form to the [Subscribers] api (https://learn.mindbaz.com/api/#operation/Subscribers_Post) or use the [Imports] api (https://learn.mindbaz.com/api/#operation/Imports_ScheduleImportOnce).

You can find our Faq articles on this subject here.

2. Choose or create a sending configuration

A sending configuration contains all the general parameters that can be reused from one campaign to another, such as: the sender email, the reply email, the aliases and the HTML/TXT headers and footers.
You will only need its id to create the campaign (idConfiguration).

To create a new sending configuration, click here.

3. Have a BAT target available

A BAT target is used to send your tests before the final campaign is sent. The BAT target id is a mandatory parameter at campaign creation (idTestTarget) and you must create one if you do not have any available. The easiest way is to use the interface but you can also do it by api.

The creation of a target is explained here.

You just have to make sure that you set the isTestTarget parameter to true (otherwise your test messages will not start). The filter to use is a "filter per field" with the input :

"filters": [ 
 {
     "idField": 1,
     "operator": 3,
     "value": "emailBat1@domain.com;emailBat2@domain.com"
   }]

This corresponds to: email (id_field=1) equals (operator = 3) emailBat1@domain.com OR emailBat2@domain.com

4. create campaign targeting in advance

Your campaign needs one or more targets to be programmed. It is this targeting that will define the list of emails that will receive the campaign. The targets used in a campaign are executed at the time of sending, but you can count them at any time to estimate their volume.

Mindbaz offers a comprehensive targeting system that addresses the most common use cases. You can create your targets in the interface (called segment) or with api Targets. Click here for more information on api targets.

You can also do your targeting outside of Mindbaz and give your target result as a file containing the list of ids or emails to use. To do this, you need to use a target with a file filter.

Steps to create your campaign

1. create the Campaign object

To create your campaign, you need to make a POST /api/{idsite}/campaigns call.

The important parameters to use to create your campaign are :

• "parameters" object: object of type CampaignParameters which contains all the parameters to configure your campaign.
• htmlContent : HTML content of the message
• textContent : TEXT content of the message

The CampaignParameters type is detailed below:

Name	Description	Type	Mandatory parameter
name	Campaign name (255 characters maximum)	String of characters	Mandatory
subject	Default message object (if not defined in segments)	String of characters	Mandatory
type	Message type	ECampaignType	Mandatory
hasTextMessage	Indicates whether the message contains text content in addition to HTML content	Boolean	false by default
idConfiguration	Send configuration identifier	Whole number	Mandatory
idTestTarget	Identifier of the target used for the BAT tests	Whole number	Mandatory
sendingSpeed ​​	Sending speed between 1 and 10,000 emails per minute	Whole number	Mandatory
idThematic	Identifier of the theme associated with the campaign	Whole number	None
isAbTest	Indicates if this is an AB Tests	Boolean	false by default
isOneshot	Indicates if this is a oneshot campaign	Boolean	false by default
isAutomation	Indicates whether this is an Automation campaign	Boolean	Deprecated
isArchive	Indicates if this is an deleted campaign	Boolean	false by default
mode	Campaign mode. Note: cannot be modified after the first sending in simple mode	ECampaignMode	Mandatory
notifyHighDelivrability	Indicates whether to target the most responsive users first in order to optimize open rates	Boolean	true by default
responseAlias ​​	Response aliases (replaces the one in the sending configuration)	String of characters	None
senderAlias ​​	Sender alias (replaces the one in the sending configuration)	String of characters	None
useListUnsubscribeHeader	Indicates whether the campaign uses the list-unsubscribe header (see rfc2369 for more information) to allow unsubscribe instead of spam reporting	Boolean	true by default
idCommonAffiliatePlatform	Affiliate platform id See api CommonAffiliatePlatform for the list of ids.	Whole number	None
idCommonAdvertiser	Advertiser id See api CommonAdvertisers for the list of ids.	Whole number	None

caution

In order to create the campaign, some parameters are mandatory, especially the name of the campaign, its mode (parameter described below), its type (also below), the subject of the default message, the sending speed and finally the sending configuration and the test target.

ECampaignMode represents the mode of a campaign.

Name	Value	Description
Unknown	-1	Mode unknown.
Simple	0	Simple mode
Dynamic	1	Dynamic mode
External	2	External mode (obsolete)

For the creation of a simple campaign via the API, the simple mode must be filled in (value 0).
For the creation of a dynamic campaign via the API, the dynamic mode must be filled in (value 1).
A dynamic campaign is rather used for customer loyalty campaigns whereas a simple campaign is more made for acquisition campaigns.

ECampaignType represents the type of a campaign.

Name	Value	Description
Unknown	0	Type unknown
Newsletter	1	The campaign is a newsletter (internal)
Dedicated	2	The campaign is of type dedicated (external partner offer)
Other	3	Campaign type is not specified (internal)
ExternalGame	4	Campaign type is partner game (external)
InternalGame	5	Campaign is a partner game (internal)
Topic	6	Campaign is a file type (internal)
Rent	7	Campaign is rental (external)
Transac	8	Campaign is transactional

The other parameters can be filled in but are not mandatory and can be specified later via a campaign modification method.

The return value of the request is the following:

Name	Description	Type
data	Result of the call to the webservice	Campaign
error	Error message in case of failure	Character string
success	Indicates success or failure of the webservice call	Boolean
typeName	Type of data contained in the Data field	String

Data is an object containing the information of the created campaign.

Example

Example of a campaign creation on db id 102: https://api.mindbaz.com/api/102/campaigns

Body :

{
  "parameters": {
    "idConfiguration": 1,
    "idTestTarget": 7037,
    "mode": 0,
    "name": "test API",
    "sendingSpeed": 100,
    "subject": "Ceci est un test",
    "type": 2
  },
  "htmlContent": "<html><body>Hello [[FIELD.15]] [[FIELD.14]]</body></html>"
}

Return value

{
  "success": true,
  "data": {
    "id": 11018,
    "parameters": {
      "idCommonAffiliatePlatform": null,
      "idCommonAdvertiser": null,
      "hasTextMessage": false,
      "idConfiguration": 1,
      "idTestTarget": 7037,
      "idThematic": null,
      "isAbTest": false,
      "isOneshot": false,
      "isAutomation": false,
      "isArchive": false,
      "mode": 0,
      "name": "test API",
      "notifyHighDelivrability": true,
      "responseAlias": null,
      "senderAlias": null,
      "sendingSpeed": 100,
      "subject": "ceci est un test",
      "type": 2,
      "useListUnsubscribeHeader": true
    },
    "htmlContent": "<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <body>Hello [[FIELD.15]] [[FIELD.14]]</body>
</html>
",
    "textContent": "",
    "creationDate": "2021-08-19T17:15:01.1710765+02:00",
    "lastUpdateDate": "2021-08-19T17:15:01.1710765+02:00",
    "schedulingInfos": {
      "calendarDates": "",
      "type": null,
      "state": null
    },
    "authorId": null,
    "authorName": null,
    "idCampDynamic": -2147483648
  },
  "error": null,
  "typeName": "Campaign"
}

You must get the id of the created campaign (data->id) to reuse it in the other calls.

You will notice [[FIELD]] tags in the HTML code of the example. They are used to make the content of the message dynamic and will be replaced by the value of the subscriber's fields (here the first and last name). For more information, click here.

2. Configure the campaign's target population

You have created a campaign object, but you have not yet defined to which target your campaign will be sent. To do this you need to create one or more segments in your campaign.

A segment is defined by :

• a number (the order of the segments is important)
• a target id
• volume (number or percentage - 100% by default)
• a random mode (yes/no)
• a subject (optional)
• a list of ads = one ad per insert [[ENCART.X]] (optional)
• exclude the segment from the mailing (yes/no)

If an email address exists in several segments, an automatic deduplication is made by prioritising the first segment. Let's take the example of a campaign with 2 segments: a first segment with a target of 6 month active users and a second segment with all my subscribers. If I am an "active 6 months", my email will be present in both targets. However, I only have to receive the campaign once. The deduplication will automatically select me in the first segment and I will be removed from the second. This is why the volume of a segment is not necessarily equal to the volume of its target.

This segmentation can be used for different reasons:

• to compare the stats of each segment
• exclude a segment (e.g. exclude @ who have already received a mailing)
• A/B test by changing the object
• display different ads between 2 segments in the same insert. Ex: display an ad for a male segment and another for a 2nd female segment

If you do not use segmentation, you will only need one segment and therefore one target.

Campaign with one segment

If you do not use segmentation, your campaign will have only one segment. By default, when the campaign is created, a segment N°1 is automatically created with your target bat as target.
All you have to do is modify the id of the target in segment n°1. To do this, make a PUT on /api/{idsite}/segments/{idCampaign}/{segmentPosition} by specifying the correct idCampaign and idTarget in the body.

php example :

//def segment 1
$fields = array(
        "name" => "tous les abonnés",
        "idTarget" => $targetId,
        "isExcluded" => false,
        "isRandom" => false,
        "percent" => 100,
        "mailobject" => null         
        );
$response = api_call($service_url.'/api/'.$dbId.'/segments/'.$campaignId.'/1', $access_token, HttpMethod::PUT, $fields);
echo var_dump($response);

Campaign with several segments

If you want to create several segments, you need to do the previous step for the 1st segment and create others by making a POST to /api/{idsite}/segments/{idCampaign}.

Here is an example in php that defines 2 segments on the same target. The first segment takes 500@ in random from the target to test a different object from the campaign. The 2nd segment takes 100% of the same target to include the remaining of the addresses in the campaign. The 2nd segment does not have a mailObject defined and will therefore use the campaign object.

php example :

//def segment 1 on 500@ to test a different object of the campaign
$fields = array(
    "name" => "segment1",
    "idTarget" => $targetId,
    "isExcluded" => false,
    "isRandom" => true,
    "fixedValues" => 500,
    "mailobject" => "mon objet à tester"         
    );
$response = api_call($service_url . '/api/'.$dbId.'/segments/'.$campaignId.'/1',$access_token, HttpMethod::PUT,$fields);
    
//add 2nd segment to add the remaining of the target
$fields = array(
    "name" => "segment2 (the remaining)",
    "idTarget" => $targetId,
    "isExcluded" => false,
    "isRandom" => false,
    "percent" => 100,
    "mailobject" => null         
);
        
$response = api_call($service_url . '/api/'.$dbId.'/segments/'.$campaignId,$access_token, HttpMethod::POST,$fields);

3.Tracking the links

The last step of your campaign setup is to track the links. All clicks on the tracked links will be recorded for your mailings and will be accessible in the stats. To easily track all links, you can POST to /api/{idsite}/trackedUrls/trackAll. This method parses the html of the campaign and automatically tracks all the urls found.

Links within ads are tracked according to the ad's tracking settings. Links in [[URL]] tags are tracked automatically according to the automatic tracking setting (e.g. unsub url).

If you want to track urls manually, you have to do a GET on /api/{idsite}/trackedUrls/{idCampaign}/all which gives you the list of urls and then do a POST on /api/{idsite}/trackedUrls/{idCampaign} for each one.

Note

if you change the HTML content of your campaign, you will have to track the links again.

4. Checking your campaign

Now that your campaign is ready, there are a few things to check.

Count the segments

You can count your segments in order to check if some of them are not empty due to the deduplication of emails in common between segments:
To count the subscribers in your campaign, do a GET on /api/{idsite}/segments/{idCampaign}/count

Test the spam score

Make a POST to /api/{idsite}/spamScores on each segment to calculate the SpamAssassin spam score and the VadeRetro score.

Note

In order to generate the customization tags in the message, you are asked for a subscriber id.

Send Tests

If you want to check your message visually before sending it, you can send a BAT message ("Good For Print"). To do this, POST to /api/{idsite}/sendings/sendBAT. A Test message will be sent for each segment (if you have several).
If you want to choose which segment to test, use /api/{idsite}/sendings/{idCampaign}/sendSegmentBAT instead

5. schedule the campaign

You can schedule your campaign for :

• an instantaneous sending with a POST on /api/{idsite}/sendings/play
• one or more future mailings with a POST to /api/{idsite}/sendings/{idCampaign}/Schedule

Monitor the progress of your campaign

To find out the status of your campaign, you need to do a GET on your campaign: /api/{idsite}/campaigns/{idCampaign}.
This api returns, in addition to the campaign information, a status(data->schedulingInfos->state) parameter which tells you the status of the scheduling: "Programmed", "ProgrammedPaused", "ProgrammedCanceled", "Sending", "SendingPaused", "SendingStopped", "SendingFinished", "SendingFinishedWithErrors", "Error", "None", "WaitingSending".

You can also act on your schedule (state="Programmed") by putting it in pause or by stopping it. If the sending has already started (state="Sending"), you can also perform a Pause or a Stop.