API SMS

This documentation presents you with a simple and effective way to send SMS via our APIs. 

Our API will allow you to integrate the functionality of sending SMS directly from your business applications. MTarget offers you a single account to route all your SMS in France and globally - we are connected to more than 700 operators in 280 destinations - simply let us know the desired destinations beforehand.


Warning: you are obliged to take into account requests from recipients not to receive any more SMS. Depending on the destination countries (determined by the telephone prefix of the mobile number), different methods can be proposed to use this right (a "STOP" Opt Out response on a Shortcode or a long number in the message sent; a link to an un-subscribe web page, etc.) and different laws and regulations can further narrow the modalities.


If you want to test our API you can use this Postman collection: here.

Registration

We would be delighted to open an account for you to test our service for free. Creating an account is non-binding, you are under no obligation. To open a test account, please send an email to support@mtarget.fr with the following information :

- Your details:

  • email account
  • name
  • surname
  • company name
  • phone number

- The static IP addresses of the servers from which messages will be sent if you want IP restriction

- In return, we will provide you with your account information to use our API.


The SMS account that we will open for you can support several offers and different tarifs depending on destinations and operators, please specify the destinations you would like to test.

Security

In order to secure your account, we offer an IP restriction on your account. You must therefore provide us with the IP(s) of your servers at the time of the creation of your account or before you start your tests. Do not forget to provide us with the IPs of the PCs or test servers, if you have them.


We can provide you with our outgoing IP so that you can put in place equivalent restrictions on your side.


The joint use of IP protection, API password protection and TLS to secure exchanges is likely to guarantee a high level of security, compatible with most needs. However, our technical teams are at your disposal to study with you the implementation of additional security mechanisms likely to meet the needs of your Information Systems Security Policy

Send SMS

Our response times to your requests are in principle well below one second. However, we advise you to set a timeout of 45s on your side. A non-response from our side should not be considered as normal behavior and should not justify the return of the request.

Authentication

When you open your account, you will be sent 3 parameters:

username : the username

password : the password

serviceid : your optional routing identifier (allows you to have several outgoing routes, only one will be assigned at the start)


Your username and password will be required in order to authenticate you for each message sent.

Accessing the service

The API is available on two URLs. If your account is set up with restricted access to certain IPs,

the URL you should use is : https://api-2.mtarget.fr/


Otherwise, the URL to use without IP control is : https://api-public-2.mtarget.fr/

This URL will always return an error message if your account is an IP controlled account.


If during your tests, our service does not respond and goes into timeout, it means that you have an IP-restricted account and that the IP you are using is not authorized.


For backwards compatibility reasons, these URLs also work in HTTP, however this behaviour is not guaranteed in the longer term, so we strongly recommend that you use the secured protocol HTTPS for all your requests.

Send a SMS in a few minutes

This is the simplest way to send a SMS: the authentication, the message and the mobile number are enough in most use cases.

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded


 BODY
usernameUSERNAME

Your username, given at registration

 passwordPASSWORD

Your password, given at registration

 msisdnMSISDN

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.

 msgMessage simple

Message content.


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 7 SMS of 153 characters each (the concatenation of SMS uses 7 characters per message). If you need to send messages longer than 7 x 153 characters, please contact support to analyse your needs. Some limitations may be imposed by operators.

Unicode SMS

It is possible to send Unicode SMS and therefore not be limited to the GSM alphabet.

However, in this mode, each character will be encoded in 16 bits, and a message will have a maximum of 70 characters (against 160 usually) - always with the possibility of sending up to 7 messages (67 characters each).

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded


 BODY
usernameUSERNAME

Your username, given at registration

 passwordPASSWORD

Your password, given at registration

 msisdnMSISDN

Number of the recipient with country code (+44...) or in international format (0044 ...). You can add up to 500 msisdn separated by a comma: +447xxxx1,+447xxxx2,+447xxxx3.

 msgMessage unicode ‼ 🥳📱

Message content.


The content of the message


The content of the message here is limited to 70 characters - the encoding used in "Unicode messages" is UCS-2. We allow with the option "long messages" to send 7 SMS of 67 characters each (the concatenation of SMS uses 3 characters per message). If you need to send messages longer than 7 x 67 characters, please contact support to analyse your needs. Some limitations may be imposed by the operators.

 allowunicodetrue

Allow unicode usage.



If the content of the SMS requires it (presence of characters not in GSM alphabet) then the SMS is sent in unicode.



Without this parameter, your message will be converted to be sent using the GSM alphabet (GSM 03.38) after transformation of the characters into equivalents.

Scheduled SMS, personalized sender

The used of scheduled SMS must concern low volumes and occasional uses. It is not recommended to use this functionnality beyond some hundred messages to be scheduled. The priority is given to immediate sending and not to scheduled SMS, so it is strongly advised not to use this functionnality to send large volumes (bulk) in the future.


Send a scheduled SMS the 19th january 2038[1], with "Test01" as sender.

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded


 BODY
usernameUSERNAME

Your username, given at registration

 passwordPASSWORD

Your password, given at registration

 msisdnMSISDN

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.

 msgMessage simple

Message content.

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 7 SMS of 153 characters each (the concatenation of SMS uses 7 characters per message). If you need to send messages longer than 7 x 153 characters, please contact support to analyse your needs. Some limitations may be imposed by the operators.

 timetosend2038-01-19 04:14:08

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, larger delays must be managed on your side. Even 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.


SMS messages programmed in the past go immediately.


 senderTest01

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)


In some countries, the sender will have to be authorized by the operators.

Contact us for more details.

The notion of sub accounts

If you need to differentiate between your requests or for billing reasons (several stores connected directly to the API for example), we can create sub-accounts to manage this eventuality. Contact us for more details.

Types of SMS and allowed times for SMS in France

In France, sending SMS is subject to regulations on when the SMS can be sent. There are two types of SMS and we have several offers: 

1. Marketing SMS

Marketing SMSs are promotional type of advertising messages used for mass communication (promotions, sales ... etc).

These SMS are authorized in France from Monday to Saturday, from 8am to 10pm. They are prohibited on Sundays and bank holidays.

In addition, the marketing messages must contain the words "STOP 36180", allowing customers to opt-out of receiving messages. 

If you send us content on a Marketing SMS offer between 10pm and 8am, the SMS will be put on hold and sent at 8am. Note that SMS sent on bank holidays and Sundays will be refused.

2. Alerting SMS

Alerting SMSs concerns notifications intended for an individual communication like reminder of appointments, deliveries of parcels, home alarms, etc.

These alerting messages are not affected by the hourly restrictions of Marketing SMS. Any marketing content is obviously formally prohibited on this offer.

All the parameters

This example uses all possible parameters. In most use cases, only the first 4 are useful.

These are not all compatibles, please read the details for each parameter.

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded


 BODY
usernameUSERNAME

Your username, given at registration

 passwordPASSWORD

Your password, given at registration

 msisdn+33600000000

Number of the recipient with country code (+44...) or in international format (0044 ...). You can add up to 500 msisdn separated by a comma: +447xxxx1,+447xxxx2,+447xxxx3.

 msgMessage 👍

Message content.

The content of the message is limited to 160 characters of the GSM Alphabet if allowunicode and dcs are not used. We allow with the option "long messages" to send 7 SMS of 153 characters each (the concatenation of SMS uses 7 characters per message). If you need to send messages longer than 7 x 153 characters, please contact support to analyse your needs. Some limitations may be imposed by the operators.

 allowunicodetrue

Allow unicode usage.

Without this parameter, your message will be converted to be send using the GSM alphabet.

 serviceid12345

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)

 senderTest01

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 issuer (for example in France NRJ Mobile or Transatel)

 timetosend2038-01-19 04:14:08

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, larger delays must be managed on your side. Even 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.

 encodingUTF-32

Allows you to specify the encoding used to send us the message (from your server to our server - we recommend the UTF-8 charset). If this field is not filled, we will look at the http headers, and if they are not set, we will assume the encoding is UTF-8.

 remoteidabcdef4567

This 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 notifications and acknowledgments. For requests with multiple numbers, you can send either a remoteid for the whole push, or a remoteid by msisdn

 uniqueidghij0123

With the msisdn, creates a unique pair that will allow us not to send the same message twice to the same number. When receiving a duplicate, we will send you the same ticket corresponding to the corresponding request (and the smscount will be 0 since we will not send an additional message). Warning, considering the mechanism in place, a negative impact on performance can be possible. Since uniqueness is guaranteed by the uniqueid-msisdn pair, you also have the choice for queries with multiple SMS to send a single uniqueid or a uniqueid by msisdn. Unlike the remoteid, we will not send you this uniqueid during notifications. It is limited to 35 characters. We check the uniqueness of the code for the current month.

 subserviceid67890

To implement this very unusual field, get in touch with us.

 dcs240

Data Coding Scheme allows you to change the class of the message.


This option is reserved to an advanced usaged and can not be used in every context. Please contact the support if you need to use it.

 pid65

Protocol Identifier allows you to replace some SMS previously sent.


This option is reserved to an advanced usaged and can not be used in every context. Please contact the support if you need to use it.

 udh0605040B8423F0

User Data Header allows you to create, for example, Rich SMS. You do not have to manage it for long messages.


This option is reserved to an advanced usaged and can not be used in every context. Please contact the support if you need to use it.

Delivery Receipt Acknowledgements (DLR)

Acknowledgments allow you to follow your message and to know its state: sent to the operator, delivered on the phone, refused, or not delivered. These will be sent on a URL defined on your server.

The requests sent are encoded in UTF-8.

You must provide us with the URL of the service which will process the delivery receipts on your server:

E.g. : https://www.mydomain.com/api-sms-receive.php


Your server will have to acknowledge the reception of our notification by answering us with a 200 - OK status. However, if you are doing slow computing tasks on your side, we suggest you answer us before performing them.

This URL will be called for each status update of your messages. Thus several states can be sent for the same message (2: sent to operator, then 3: delivered). It is advised to keep the highest status because the DLR can arrive out-of-order.

Here is the request that will be sent to your server:

POST https://your.url.example/dlr HEADERS
Content-Typeapplication/x-www-form-urlencoded


 BODY
MsgIdeda25190-c02d-11e9-89e2-00000a0a6447

Unique Message ID per message. This is sent in the synchronous response under the name of ticket

 Status3

Represents, with StatusText, the SMS status.

 StatusTextdelivered

Represents, with Status, the SMS status.


The possible statuses are:


0 – waiting : Waiting


1 – in progress : In progress


2 – sent : Sent to the operator


3 – delivered : Delivered


4 – refused : Rejected by the operator


6 – not delivered : Not Delivered

 DestinationAdress+33612345678

Recipient number in international format (+447xxxxxxxx)

 OriginatedAddress00000

Either 00000, or any senderID specified in SENDER

 CreateDateTime2019-02-18 12:54:23

Creation date and time (format yyyy-MM-dd HH:mm:ss)

 SendDateTime2019-02-18 12:54:23

Time the operator has acknowledged receipt of the SMS (format yyyy-MM-dd HH:mm:ss)

 DeliveryDateTime2019-02-18 12:54:25

 Time of the recipient mobile ack (format yyyy-MM-dd HH:mm:ss)

 ReasonOK

 Specific reason coming from the operator

 RSN0

SMS Result code Code

 SmsCount1

Number of Sms sent 

 remoteidabcdef4567

This 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 notifications and acknowledgments. For requests with multiple numbers, you can send either a remoteid for the whole push, or a remoteid by msisdn

Reply management (MO)

If the operator handles replies from the final user (MO : Mobile originated) - they will be sent on a second URL (advices given in the "Delivery Receipt Acknowledgements" section also apply).

Ex : https://www.mydomain.com/api-sms-mo.php

For France, this URL will be called for each reply sent. For replies in Italy, contact commercial@mtarget.it. In most cases, MOs in foreign destinations are not received.

POST https://your.url.example/mo HEADERS
Content-Typeapplication/x-www-form-urlencoded


 BODY
MsgIdc8120070-bff0-11e9-ad94-00000a0a820a

Unique identifier of a message

 Status5

Status is always 5 for the replies

 StatusTextSMSMO-received

StatusText is always SMSMO-received for the replies

 Msisdn+33612345678

The sender mobile number with country code (+44...)

 ShortCode36180

Short number on which we received the MO

 SendDateTime2019-02-18 17:31:06

Time when we received the message (format : yyyy-MM-dd HH:mm:ss)

 ServiceId12345

The ServiceId corresponding to the two way messaging – uou will have only one by default. 

 SubServiceId0

The corresponding SubServiceId, it will be 0 by default

 OriginMsgIdeda25190-c02d-11e9-89e2-00000a0a6447

The ticket to which the reply has been sent to

 ContentSTOP

The content of the received message

 KeywordStop

Might be a keyword if implemented, will be Default by default. Will be Stop if the MO has been identified as an opt-out on our side. Please note, the responsability for qualifying the MO as an opt-out request remains with the client. The Keyword field is given for information only.

 RemoteIdabcdef1234

Allows you to get the remoteid field present when MT is send. Watch out, this field is case-sensitive, and it is different between both calls.

Check your balance

This request allows you to check your balance. There may be a delay before operations are taken into account. Due to asynchronous processing, your balance may be slightly negative.

If you have a postpaid account, the fields amount and currency will not be given.

POST https://api-public-2.mtarget.fr/balance HEADERS
Content-Typeapplication/x-www-form-urlencoded


 BODY
usernameUSERNAME

Your username, given at the registration

 passwordPASSWORD

Your password, given at the registration

Error codes

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

  • -1 : Authentification failed
  • -2 : Invalid destination address. Incorrectly formatted msisdn field.
  • -3 : Invalid operator
  • -4 : No route defined. If you get this error, you are probably trying to send a SMS to a country which is not cabled on your account. If you want to add it, please contact support@mtarget.fr.
  • -5 : No transaction found
  • -6 : Parameter "method" not found. Check parameters
  • -7 : Time to send not allowed
  • -8 : Datacoding scheme invalid
  • -9 : Serviceid not found
  • -10 : Message too long
  • -11 : Not enough credit
  • -12 : Invalid parameter
  • -13 : PushAction not found 
  • -14 : Maximum message limit
  • -15 : PID invalid


Changelog

2019-12 : First version of the online documentation

2020-02 : Added section error codes