Send transactional emails

Why use them?

Transactional emails can take many forms:

• Double opt-in confirmation email
• Welcome email
• Payment confirmation
• Shopping cart reminder
• Invoice sending...

But they have several points in common:

• They must be sent quickly. Immediately after an action of the Internet user.
• Their content is personalized for each individual

The api Oneshot answers this use case and allows you to use your Mindbaz sending ips for your transactional emails.

A oneshot sending must be associated to a campaign id. This campaign will be used to consult your statistics (openings, npai...). The oneshot will also use the parameters of this campaign as default value for its sending. For example, concerning the HTML code of your transactional message, you have 2 possibilities:

• Use the HTML code defined in the Mindbaz campaign
• Pass it as a parameter to the oneshot methods

Modes of operation

You provide the html and text content

You generate the content of your messages yourself and pass it directly as a parameter to each oneshot call.
To do this, make a POST to /api/{idsite}/OneShot with, for example, the input:

{
  "campaignId": 9543,
  "subscriberId": 34,
  "messageHTML": "sample string 4"
}

Limitations:

• As the content of messages can be different on each call, we do not store the message history and cannot display the mirror page.
• If you use customization tags ([[FIELD.XX]]) in your HTML/TXT message or object, you must specify the ids of the fields used in the idFields parameter. If not specified, ids 0,1,7,8,13,14,15 are used by default.
• The mindbaz tracking will only work for openings. Links will not be tracked because urls can change between several oneshots, so tracked links are no longer identifiable. However, there is a solution by making the urls of tracked links dynamic. Using custom tags, the tracked url will remain the same and will be identifiable. (See "Making the content of an Oneshot dynamic" for more information)

The html and text content comes from the mindbaz campaign

The html code is identical for each call. You can therefore directly manage the html code of your transactional emails in your mindbaz campaign. The tracking of links and openings will work.
To do this, POST to /api/{idsite}/OneShot with input:

{
  "campaignId": 9543,
  "subscriberId": 34
}

Return codes

A return code is sent in the "data" parameter of the response:

code	description
OK	the oneshot is sent
KO(CAMP_DELETED)	if the campaignId is deleted.
KO(EMAIL_NOTFOUND)	if the input email does not exist.
KO(EMAIL_UNSUB)	if the email is unsubscribed or cleaned. You can allow your oneshot to be sent on an unsubscribed status if your campaign is of type Transactional (Type="Transac").
KO(SMTP_ERROR){{....}}	an smtp error has occurred on the ips. The cause may be too many spam complaints on the ip or a too fast sending speed. A retry is necessary (preferably after several hours).

Making the content of an Oneshot dynamic

Making the content of the message dynamic allows you to transform your message into a "template". The HTML code of your campaign will be the same for all the oneshot calls of a campaign, but its content will change according to the subscriber. This makes the code easier to maintain, calls are faster and link tracking becomes possible.

The simplest method is to use customization tags. For example, [[FIELD.0]] displays the subscriber's id, [[FIELD.1]] their email, [[FIELD.14]] their name, etc. This is very useful if you need to display information that is already in the subscriber table.

However, if this information is not available in this table, there is another solution. This is often the case when the data to be displayed is recent or if importing it into the mindbaz database is too expensive. This could be the contents of an abandoned shopping basket, for example.

This data can be sent in the form of a json at the same time as the call of the oneshot in the emailData parameter. Here is an example with 2 data fields:

"emailData" = "{  
    name : 'greg',
    product_name : 'iphone 13' 
}"

To use these 2 values in my HTML code, I need to use the [[json.parameter]] tag. In our example, [[json.name]] will display "greg" and [[json.product_name]] will display "iphone 13".

Here is a example in php :

<?php
session_start();

include 'mbzApi.php';

$access_token = GetAccessToken('user_*****','***********' );

$service_url = 'https://api.mindbaz.com';
$dbId = '1234';

//send oneshot to subscriber id 667175 with campaign id 11991
$fields = array("campaignId" => 11991,
     "subject" => "test oneshot",
    "messageHTML"=> "bonjour [[json.name]], <br>produit acheté : [[json.product_name]]",        
    "emailData"=>"{  name    : 'greg',  product_name  : 'iphone 13' }",
    "subscriberId" => 667175
);   
 
$result = api_call($service_url . '/api/'.$dbId.'/OneShot',$access_token,HttpMethod::POST, $fields );

?>

Send a oneshot with an attachment

You can pass attachments in your oneshot calls (this is not possible with the classic campaign sendings).

To provide attachments, you must fill in the "attachments" parameter, in the form of an array of elements {"fileContent", "fileName"}:

• fileContent: content of the file encoded in base64
• fileName: name of the attached file.

Attention

• Only pdf files are accepted!
• The maximum number of attachments allowed is 3
• The total file size must not exceed 2 MB.

Here is an example in php that adds a card.pdf attachment:

<?php
session_start();
include 'mbzApi.php';

$access_token = GetAccessToken('user_********','********' );

$service_url = 'https://api.mindbaz.com';
$dbId = '1234';
$fileName = "card.pdf";
$fileContent = file_get_contents("C:\\filepath\\".$fileName);
$fileContent = base64_encode($fileContent);
 

//send oneshot to subscriber id 667175 with campaign id 11991
$fields = array("campaignId" => 11991,
        "subject" => "test oneshot avec piece jointe",
        "attachments" => array(
                            array("fileContent"=>$fileContent,"fileName"=>$fileName)
                            ),       
        "subscriberId" => 667175);  
 
 
$result = api_call($service_url . '/api/'.$dbId.'/OneShot',$access_token,HttpMethod::POST, $fields );
?>

Statistics

You can find the statistics of your oneshot mailings directly in the application interface or with the api Statistics/campaigns. If the same campaign id is used by oneshot mailings on several days, a sending id is automatically created each day. This way you can access your campaign statistics day by day.

Rate limiting

In order to prevent abuse of the webservice to send mass emails, we limit the number of calls per ip to 4000 calls per minute. As long as the call volume exceeds this threshold, a 429 http error will be returned.