SMS HTTP sending API

1 SMS API/account activation

In order to use our SMS sending API, you must have a working PushSMS Pro account including the API option.

Upon your account activation, you will receive API credentials (auth key, service URL, etc.).

You may request for security reasons that your account be restricted to a limited set of source IP addresses allowed to query the API. Please contact our tech support team.

For historical reasons, the current version of this API uses french wording in parameters and settings. Furthermore, current english version doesn't include list editing functions. Please contact Axialys if needed.

2 Variables description

VariableDescriptionTypeExample
cleCustomer identification key. Mandatory in every requestAlphanum 16my_key
passIdentification pasword. Mandatory in every requestAlphanum 16HardToGuess
IDCustomer transmission ID. This variable, if set, lets you track the transmission (acknowledgements, replies…)Alphanum 16abc123456
ID2Accounting ID. This variable, if set, enables the production of per account statisticsAlphanum 16client1
listeList identifierNum 101034
numeroPhone number (MSISDN), E164 formatNum 2033619000000
nom, prenom, usr1, usr2, numerosCustomization fields. The message can be customized by setting the corresponding ##NOM##, ##PRENOM##, etc. Must be all caps in the messageAlphanum 32John
numerosPhone numbers listAlphanum
contenuMessage content. Messages longer than 160 IA5 characters will be split (and billed) as several messages.AlphanumThis is a test message !
typeSTANDARD : standard SMS transmission, REPONSE : ability to receive repliesAlphanum 8STANDARD
dateApproximate date for the transmission to happen (or when the message was received). Format YYYYMMDDHHmmSS.Num 1420150118173022
emetteurSender to be displayed when the SMS is transmitted. Note that setting this disables the ability to receive replies. Depending on countries, what is allowed as a valid sender varies.Alphanum 16Axialys
ttlMaximum date for message transmission (message will be cancelled by the network if it has not been transmitted by then). Format YYYYMMDDHHmmSS.Num 1420150118173022
marketingSpecifies transmission type : 0 for standard notification, 1 for marketing (bulk transmission)Num 10
formatSelects API output format. Values available are : csv (without header), csv_header (with header), jsonAlphanum 10json
encodageSet UTF-8 if not using the default ISO-8859-1Alphanum 10
mode_envoiSending mode for SMS content. Either LATIN1 (default) or ETENDU. Beware that in this case, multibyte transmission is enabled, thus the number of letters available in an SMS is divided by two.Alphanum 10LATIN1

3 Sending SMS (MT)

A message can be sent to one or more GSM subscribers. It can also be sent to a pre-arranged diffusion list.

Variables used for this method are :

  1. mandatory : cle, ID
  2. optional : numero, liste, type, date, ttl, ID2, emetteur, mode_envoi
At least liste, numero or numeros must be specified.
Content must of course be properly encoded using standard URL encoding scheme.

Example sending to several numbers :

http://api-sms.sites.axialys.net/get/send.php?
cle=dd&ID2=axe&pass=pass&numeros[]=336100000000&numeros[]=336100000001&id=ax&contenu=Hello+World

Example sending to a list :

http://api-sms.sites.axialys.net/get/send.php?
cle=dd&ID2=axe&pass=pass&liste=10&id=ax&contenu=Hello+list&emetteur=AXIALYS

This method return a status message (OK or otherwise) as soon as the transmission has been registered by Axialys.

4 Receiving SMS (MO)

It is possible to get the reply if the subscriber who has received an MT message replies to it.

The API will call the URL specified by the client.

Received variables are as follows :

VariableDescription
TypeMO
IDIdentifier set when the message was sent
numeroSending number in E164 format
dateDate (GSM network provided) of the event.
EtatReturned message

5 SMS billing

Depending on the transmission parameters, the number of characters included varies. The number of SMS billed varies accordingly.

“Marketing” messages towards France include a mandatory part automatically added, enabling the recipient to reply with STOP in order to un-subscribe from any further transmission from this source. This is mandated by french law.

As a reminder, messages can be made of up to 5 SMS. New lines count for 2 characters.

Here is a quick summary of the number of SMS billed vs the number of usable characters in the message :

Type/Cost 1 SMS 2 SMS 3 SMS 4 SMS 5 SMS
Notification 160 280 420 560 700
Marketing 150 270 410 550 690
Extended character set 70 134 201 268 335

6 Receiving acknowledgments

6.1 Intro

Our platform lets you receive acknowledgements from the MNO in order to track messages delivery.

For that purpose, our API server will make an HTTP call to your own server. You thus need a publicly accessible web server.

Please get in touch with our Support team in order to set/change your callback URL.

6.2 Callback format

The callback is performed as an HTTP GET method on the client specified URL.

A single message transmission may trigger several callbacks, at each message state change.
VariableDescription
TypeACK
IDIdentifier set when the message was sent
numeroSending number in E164 format
dateDate (GSM network provided) of the event.
EtatMessage state code, see below.

6.3 Messages states

State Description
1 Message sent
2 Platform issue
5 Message expired
6 Invalid syntax
7 Subscriber out of coverage area
8 Unknown error
9 Service temporarily unavailable
10 Unknown subscriber
11 Ported number
12 Pending
13 Message received
14 Destination not included in package
15 Destination black listed
16 Incompatible phone
17 Insufficient balance
18 Undeliverable message
20 Transmission pending
21 Bulk transmission pending
23 Invalid subscriber
24 Unreachable subscriber
25 Blocked by the operator (no STOP)
26 Blocked by the operator (credit)

7 Blacklist

You can manage your blacklist via the following methods:

  • get_bloques: get list of blocked numbers
  • add_bloque: block a number
  • del_bloque: remove a number from your blacklist
At least numero must be specified with “add_bloque” and “del_bloque”. (E164 without “+”)

Example to get your blacklist :

http://api-sms.sites.axialys.net/get/get_bloques.php?
cle=dd&ID2=axe&pass=pass&format=json

Example to add a number to your blacklist :

http://api-sms.sites.axialys.net/get/add_bloque.php?
cle=dd&ID2=axe&pass=pass&format=json&numero=336000000000

Example to remove a number from your blacklist :

http://api-sms.sites.axialys.net/get/del_bloque.php?
cle=dd&ID2=axe&pass=pass&format=json&numero=336000000000

8 Standard SMS character set

The table below, which is a subset of the ISO-8859-1 charset, lists the characters allowed in normal SMS messages.

If other characters are required, the request shall be submitted with the ETENDU value for mode_envoi, and the message itself should be UTF-8 encoded.

LF CR
SP!#$%@'()*+,-./
0123456789:;<=>?
@ABCDEFGHIJKLMNO
PQRSTUVWXYZ _
abcdefghijklmno
pqrstuvwxyz
i £¤¥ §
ÄÂÆÇ É
Ñ Ö Ø Ü ß
à äâæ èé ì
Ñò ö øù ü