API Campaign

This document provides you with an overview of the API Campaign, an add-on to our main API to send SMS.

It allows you to send SMS in packets. For the system to be effective, we recommend that you use the API Campaign only for large quantities of SMS (specifically you should use the standard API for single SMS and for Transactional SMS )

Registration

In order to use the API, please send an email to support@mtarget.fr with "Creation of an API Campaign account" in the subject giving the following information: name, surname, company name, phone number, registration number.

Send SMS

The API Campaign is recommended only when the API SMS is not adapted to your needs. We will have to exchange before to analyse your needs and why you need to use the API Campaign.

Your username and your password will be needed to authenticate you for each campaign sent.

Campaign integration

First we will ask you to limit your campaign to 50 000 messages at a time and to consult us before increasing it ; and to take notice off the returned error when exceeding the limit - you will receive a HTTP 413 Request Entity Too Large.


POST https://api-public-2.mtarget.fr/api-campaignsms HEADERS
Content-Typeapplication/json


 BODY
{
 
  "username": "USERNAME",

Your username, given during the registration.

 
  "password": "PASSWORD",

Your password, given during the registration.

 
  "sender": "APICampaign",

Personalization of the Sender ID : 11 alphanumeric characters, for example "MyStore" (the default value differs according to countries and operators). Some operators will refuse the personalization of the Sender (for example in France NRJ Mobile or Transatel).


 
  "msg": "Ceci est un message de test simple avec un parametre : [param1]",

Message content.

 


You can use [parameters] between brackets, which will need to be given for each number to personalize the SMS.


The content of the message is limited to 160 characters for a standard SMS (which uses the GSM alphabet - beware of double counting characters, such as €). We allow with the option "long messages" to send up to 5 SMS of 153 characters each (the concatenation of SMS uses 7 characters per message). If you need to send messages longer than 5 x 133 characters, please contact support to analyse your needs. Some limitations may be imposed by operators.

 
  "timetosend": "2019-01-01 10:15:00",

Date and hour to send the message (format: YYYY-MM-dd HH:mm:ss ex: 2038-01-19 04:14:08). The timetosend can not be used to send more than 24h in the future, longer time periods must be managed on your side. Once scheduled, it is not possible to cancel a message. The time zone is that of France. If a recipient express his will to not receive SMS anymore (STOP), you can not handle the case of an already scheduled message.

 
  "serviceid": 11111,

Allows you to manage several different offers on a single account (for example: an offer for Alerting messages and an offer for Marketing messages in France).

 
  "msisdns": [
    {
        "msisdn": "+336xxxxxxxxx",
        "param1": "parametre #1",
        "remoteid": "remoteid1"
    },
    {
        "msisdn": "+337yyyyyyyyy",
        "param1": "parametre #2",
        "remoteid": "remoteid2"
    }
  ],

Array with all the msisdns (Number of the recipient with country code (+44...) or in international format (0044 ...). You can add up to 500 msisdns separated by a comma: +447xxxx1,+447xxxx2,+447xxxx3.). If you used [parameters] in the message, you will have to set here their values for each msisdns. remoteid is a free field limited to 250 alphanumeric characters, that allows you to give us a business identifier that we will send you back in the report.



 
  "validationrequired": true,

If this parameter is set to true, you will have to validate the campaign before the push with the method below (if not, the campaign will be sent immediatly). We advise you to always set it to true, it allows you to check the number of SMS, which can differ from the number of messages in case of long SMS.


Attention: this is not a mechanism to differ a push. We have the right to delete the campaigns waiting for validation for too long.

 
  "packetsize": 50,

Optional field: works with the interval field. This option allows you to delay your SMS: X SMS every Y seconds (packetsize as X and interval as Y)

 
  "interval": 300,

Optional field: works with packetsize. Value in seconds.

 
}

Campaign status

This request allows you to see the campaign state and the number of SMS which will be sent. The numbers are frozen when the parameter campaignstate is 18 (awaiting validation).


GET https://api-public-2.mtarget.fr/api-campaignsms?username=USERNAME&password=PASSWORD&action=getstate&campaignid=12345678 PATH PARAMETERS
usernameUSERNAME

Your username, given at registration

 passwordPASSWORD

Your password, given at registration

 actiongetstate


 campaignid12346578

The campaign id obtained when integrating the file.

Campaign validation

If the validationrequired parameter has been used (and set to true), the campaign is integrated but not sent. To start the push, you need to use the following method. This process allows you to validate the number of SMS which will be sent.

Attention: this is not a mechanism to differ a push. We have the right to delete the campaigns waiting for validation for too long.

Attention 2: this request needs the header content-type to be application/x-www-form-urlencoded.


POST https://api-public-2.mtarget.fr/api-campaignsms?username=USERNAME&password=PASSWORD&action=validation&campaignid=12345678 PATH PARAMETERS
usernameUSERNAME

Your username, given at registration

 passwordPASSWORD

Your password, given at registration

 actionvalidation


 campaignid12346578

The campaign id obtained when integrating the file.

Report generation

After the campaign is sent, it is possible to obtain a report (it is better to wait few hours after the start of the campaign to have significant results).  The report is in principle final 3 days after the end of the campaign. 


GET https://api-public-2.mtarget.fr/api-campaignsms?username=USERNAME&password=PASSWORD&action=report&campaignid=12345678 PATH PARAMETERS
usernameUSERNAME

Your username, given at registration


 passwordPASSWORD

Your password, given at registration


 actionreport


 campaignid12346578

The campaign id obtained when integrating the file.

Error codes

You can find here an exhaustive list of the API's error codes:

  • 0, "success"
  • 1, "authentification failure"
  • 2, "user not allowed"
  • 3, "validation failure"
  • 4, "report not available"
  • 5, "report not available. service temporary unavailable"
  • 6, "The report not yet available."
  • 7, "setState not allowed"
  • 8, "setState not allowed. The campaign must be validated."
  • 9, "action not implemented"
  • 10, "campaign not found"
  • 11, "Content-Type not found in http header"
  • 12, "Erreur lors traitement. erreur:xxxxxxxx"
  • 13, "Erreur lors de la recuperation des donnĂ©es. "
  • 14, "Erreur lors traitement du JSON. erreur:xxxxx"
  • 15, "Erreur lors traitement. erreur:xxxxx"
  • 16, "Content-Type: xxxxxx not implemented"
  • 17, "Erreur lors traitement des donnĂ©es. "
  • 18, "Erreur lors traitement des donnĂ©es. Msgcount=0"
  • 19, "authentification failed. Account disabled."
  • 19, "Not enough credit. Account disabled."
  • 500, "service temporary unavailable"