SMS HTTP(S) API v4.1.0

1. Introduction

HTTP Bulk Service API enables customers to send SMS over HTTP/HTTPS and to receive Delivery Reports (DLRs) over the same protocol.

1.1 Help with Formatting Special Types of Messages

HORISEN HTTP Bulk Service API helps customers to format special types of messages, such as concatenated messages and WSI (WAP Service Indication) messages. HTTP Bulk Service API may split the submitted message into several physical SMS messages (concatenated messages) or reject the message because it is too long. Customer balance is charged per physical SMS, as in details described in the following text.

1.2 Integration

Integration libraries are available on the following links:




2. Protocol Description

This chapter provides information about the supported types of bulk SMS messages and the data flow of the messages and delivery reports.

It also provides information on the types of cases for the delivery status of the messages.

2.1 Types of Bulk Messages

Customers can send different types of messages:

  • GSM Text messages
  • Unicode Text Messages
  • WAP Service Indicators (WSI)

2.2 Data Flow of Message and Delivery Reports

The message is submitted over HTTP/HTTPS from the customer to HORISEN HTTP Bulk Service API. When API has information on what happened with the delivery of the message (described in 2.5.2 Delivery Report Events section), it will send (also using HTTP/HTTPS) an event to the Callback DLR URL provided by the customer.

There are four cases:

  • Delivered message (DELIVERED)
  • Undelivered message (UNDELIVERED)
  • Rejected message (REJECTED)
  • Buffered (temporary undelivered) message (BUFFERED) followed by final DLR event, delivered (DELIVERED), undelivered (UNDELIVERED) or rejected (REJECTED)

When the message cannot be delivered as fast as possible due to temporary problems and if the DLR mask allows sending buffered events to customers for each delivery attempt, DLR event Buffered will be sent to the Callback DLR URL, as described in 2.2.4 Buffered (Temporary Undelivered Message) section.

If the DLR mask does not allow sending DLR event Buffered to the customer, no notification will be provided until the final event, Delivered or Undelivered. When the message is delivered (at first attempt or at any latter attempt), DLR event Delivered will be sent, as described in 2.2.1 Delivered Message section.

When the Bulk Service decides that a message cannot be delivered (at first attempt or at any latter attempt or when message validity expires), a DLR event Undelivered will be sent, as described in 2.2.2 Undelivered Message section.

When the message is rejected immediately on submission, the customer will be informed with HTTP response about the reason, as described in 2.2.3 Rejected Message section. Rejection may also happen later, and the customer will be informed using DLR event Rejected.

The following sections explain these cases more in detail.

2.2.1 Delivered Message

When a customer submits an SMS to HORISEN Bulk System, the message will be delivered to its destination as fast as possible. When HORISEN Bulk System receives confirmation from a destination that the message is delivered, it will send a DLR Event Delivered to Callback DLR URL.

Delivered Message Data Flow

Figure: Data flow for delivered message

2.2.2 Undelivered Message

This case is similar to Delivered Message except it describes a failure in delivery. Callback DLR URL will be called with DLR event Undelivered and a reason. No further attempt to deliver will be made. Messages are undelivered in cases when:

  • The destination number does not represent an existing mobile phone.
  • There is no route to the required destination.
  • If HORISEN Bulk System was not able to deliver the message to the phone during the validity period (which is by default 24 hours).
  • In case of some other permanent error that makes a delivery to mobile phone impossible.

Undelivered Message Data Flow

Figure: Data flow for undelivered message

2.2.3 Rejected Message

Messages can be rejected by HORISEN Bulk System in several cases:

  • When the username and/or password submitted in the request don't match the one configured for the account.
  • When the account is disabled.
  • When there is no money on the account balance.
  • When the destination is not allowed for the customer.
  • When the sender field contains not allowed characters.
  • When the format of any parameter is not correct.
  • When the contents of some parameter (for example parameter text for text message submission) contains characters not supported with selected data coding.
  • Rejection can happen:
    • immediately on submission, in which case the error will be returned to the customer with HTTP/HTTPS response on the submission request.
    • or it can happen later, in which case the Callback DLR URL will be called with the DLR event Rejected.

Rejected Message Data Flow

Figure: Data flow for rejected message

Data flow for the message that is rejected later, after successful submission:

Rejected Later Message Data Flow

Figure: Data flow for message that is rejected later, after successful submission.

2.2.4 Buffered (Temporary Undelivered) Message

If HORISEN HTTP Bulk Service cannot deliver the message at the first attempt, and the DLR mask allows sending of buffered messages to the customer, DLR will be sent to the customer for each attempt with the reason of temporary failed delivery.

Reasons for temporary failures can be:

  • Absent subscriber (subscriber is not within reach of destination network or his phone is offline).
  • The mobile phone buffer for SMS is full.
  • Any other temporary failures of mobile device or destination mobile network when there is a chance to be resolved within the message validity period.

HORISEN Bulk System will stop trying to deliver the message in the following situations:

  • The message is successfully delivered, in which case the DLR event Delivered is sent.
  • A permanent error happened which makes delivery impossible (e.g. the destination number does not exist). DLR event Undelivered or Rejected is sent.
  • Message validity period expired - within the validity period, HORISEN Bulk System was not able to deliver the message to the mobile phone. DLR event Undelivered or Rejected is sent.

Buffered Message Data Flow

Figure: Data flow for buffered (temporary undelivered message)

2.3 Sending SMS

Messages are sent using POST HTTP Method, to the URLs provided together with the credentials.

HTTP Post JSON payload must be encoded using UTF-8 encoding.

2.3.1 JSON Fields in Submitted Message

JSON fields in submitted message, common for all types:

Name Type Description
type string Type of a message. It can be: text or wsi.

  • For type='text':
    - text - UTF-8 encoded text of message content,
    - dcs - message coding, gsm (for GSM messages) or ucs (for Unicode messages).
  • For type='wsi':
    - url - URL to show in WSI,
    - title - Title of WSI.
sender string SMS originator address, alphanumeric or numeric.
receiver string SMS destination address, numeric.
dlrMask integer DLR mask represents DLRs customer wants to receive, described in the following text (optional, default=19).
dlrUrl string DLR URL where to send DLR callbacks (optional, if not present, the one set in an account settings in the platform is used).
custom object Custom JSON object that will be sent back as a part of each DLR (optional, default empty).
auth object Authentication object with two fields:

  • username - account username
  • password - account password.

2.3.2 Example of Submission URLs

  • For HTTP:
  • For HTTPS:

NOTE: Instead of '' please use URLs provided to you in Excel file with your account data.

2.3.3 Text Messages in GSM Encoding

SMS to be sent is encoded in JSON document:

    "type": "text",
    "auth": {"username": "testuser", "password": "testpassword"},
    "sender": "BulkTest",
    "receiver": "4179123456",
    "dcs": "GSM",
    "text": "This is test message",
    "dlrMask": 19,
    "dlrUrl": ""

and it must be submitted to the URL (HTTP or HTTPS) that is given together with the credentials.

2.3.4 Examples (From Bash Shell)


    "type": "text", 
    "auth": {"username": "testuser", "password": "testpassword"}, 
    "sender": "BulkTest",
    "receiver": "41787078880", 
    "dcs": "GSM", 
    "text": "This is test message", 
    "dlrMask": 19, 
    "dlrUrl": ""

curl -L "" -XPOST -d "$CONTENT"


    "type": "text", 
    "auth": {"username": "testuser", "password": "testpassword"}, 
    "sender": "BulkTest",
    "receiver": "41787078880", 
    "dcs": "GSM", 
    "text": "This is test message", 
    "dlrMask": 19, 
    "dlrUrl": ""

curl -L "" -XPOST -d "$CONTENT"

NOTE: Instead of '' please use URLs provided to you in Excel file with your account data.

2.3.5 Unicode Messages

    "type": "text",
    "auth": {"username": "testuser", "password": "testpassword"},
    "sender": "BulkTest",
    "receiver": "4179123456",
    "dcs": "UCS",
    "text": "This is test message with some UTF-8 characters üöä€ ",
    "dlrMask": 19,
    "dlrUrl": ""

Message text must be UTF-8 encoded as well, but it will be sent to the destination device encoded using UTF-16 protocol. Content is converted by Bulk Service.

Note that GSM messages, when long, need to be encoded to 140 bytes or 160 septets when content is converted to GSM encoding. Available number of bytes is further reduced by the length of the UDH (used for concatenation). Unicode messages use the same number of bytes (140) but require more bytes for each character (UTF-16 encoding). This means, when message content is longer, and must be sent as concatenated parts, Unicode messages will require more parts than GSM messages.

2.3.6 WAP Server Indication (WSI) Messages

    "type": "wsi",
    "auth": {"username": "6666_TESTHTTP", "password": "TerWAvAs"},
    "sender": "BulkTest",
    "receiver": "41787078880",
    "url": "",
    "title": "HORISEN",
    "dlrMask": 19,
    "dlrUrl": ""

2.3.7 HTTP Response When Sending SMS

If the message is accepted to be sent, HTTP status code is 202 and JSON response is:

    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
    "numParts": 2


  • msgId - message ID formatted as UUID and used for referencing further this message, for example in DLR.
  • numParts - number of parts if the message is concatenated. If the message can be sent as one SMS part (without concatenation), numParts will be 1.

If the message is rejected, the HTTP status code is 420 and the response is:

    "error": {
        "code": "107",
        "message": "Invalid sender"

API may also return other error codes from the 5xx range. In this case, there is no JSON response and error codes conform to standard HTTP error codes.

2.4 Error Codes

Error codes are listed in the following table:

Error code Value Description
RC_APPLICATION_ERROR 101 Internal application error.
RC_ENCODING_ERROR 102 Encoding not supported or message not encoded with selected encoding.
RC_NO_ACCOUNT 103 No account with given username/password.
RC_IP_NOT_ALLOWED 104 Sending from clients IP address not allowed.
RC_THROTTLING_ERROR 105 Too many messages were submitted within a short period of time. Resend later.
RC_BLACKLISTED_SENDER 106 Sender contains words blacklisted on destination.
RC_INVALID_SENDER 107 Sender contains illegal characters.
RC_MESSAGE_TOO_LONG 108 The message is too long.
RC_BAD_CONTENT_FORMAT 109 The format of the text parameter is wrong.
RC_MISSING_MANDATORY_PARAMETER 110 Mandatory parameter is missing.
RC_UNKNOWN_MESSAGE_TYPE 111 Unknown message type.
RC_BAD_PARAMETER_VALUE 112 Format of some parameter is wrong.
RC_NO_CREDIT 113 No credit on account balance.
RC_NO_ROUTE 114 No route for given destination.
RC_CONCAT_ERROR 115 Message cannot be split into concatenated messages (e.g. too many parts will be needed).
RC_LOOP_DETECTED 116 Loop detected.

2.4.1 How to Handle Errors

When the customer receives an HTTP status code 420 METHOD_INVOCATION_FAILURE, he should not retry the submission of the message, except in the case of RC_THROTTLING_ERROR. Throttling Error

In case when submission fails with RC_THROTTLING_ERROR, the customer should wait one second and then retry the submission. Internal server Error

In case when submission fails with HTTP status code 500 INTERNAL_SERVER_ERROR, the customer should wait at least one minute and then retry the submission.

2.5 Receiving DLR

Delivery reports are sent to the customer to the URL provided in JSON field "dlrUrl" when submitting an SMS. Alternatively, the account could be set up with a default value for "dlrUrl".

It is JSON encoded, with the following form:

    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
    "event": "DELIVERED",
    "errorCode": 0,
    "errorMessage": "",
    "partNum": 0,
    "numParts": 1,
    "accountName": "testuser",
    "sendTime": 0,
    "dlrTime": 2

The previous JSON is an example of DLR for a message that is not concatenated (numParts=1), then partNum is 0.

Fields in DLR:

Name Type Description
msgId string ID of the message, the one returned when SMS is submitted.
errorCode integer Error code, a reason for delivery failure (check DLR error code list in the next section). Zero represents no error.
errorMessage string A message associated with errorCode.
numParts integer Total number of concatenated parts. If message is not concatenated then numParts=1.
partNum integer A number of a message part. It can be from [0..numParts-1] interval.
  • If message is not concatenated, then numParts=1. Then partNum=0.
  • If message is concatenated of two parts i.e. numParts=2, then partNum is one from [0, 1] interval.
sendTime integer Seconds passed from SMS submission until Bulk Service successfully sent SMS to the route (next hop).
dlrTime integer Seconds passed from SMS being sent to the route (next hop) until the delivery report was received.

Depending on an account settings, DLR may contain additional fields:

  • mcc - Mobile Country Code discovered for the destination number.
  • mnc - Mobile Network Code discovered for the destination number.
  • country - ISO2 code of the country where the destination number is registered.
  • price - The price of the SMS (this information is informal and may be subject to change).
  • currency - The currency of the price.

If SMS is submitted with "custom" field, DLR will have:

  • custom - The same object sent back in each DLR.

When a message is concatenated, it is submitted by the customer as one submission, and then split by Bulk Service to required number of SMS parts. DLRs are sent to the Callback URL for each SMS part independently.

2.5.1 Example of DLRs for a Concatenated Message

  1. An example of DLR for the first part of a concatenated message of two parts, i.e. numParts=2, then partNum=0:

        "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa5e",
        "event": "DELIVERED",
        "errorCode": 0,
        "errorMessage": "",
        "partNum": 0,
        "numParts": 2,
        "accountName": "testuser",
        "sendTime": 0,
        "dlrTime": 2
  2. An example of DLR for the second part of a concatenated message of two parts, i.e. numParts=2, then partNum=1:

        "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa6g",
        "event": "DELIVERED",
        "errorCode": 0,
        "errorMessage": "",
        "partNum": 1,
        "numParts": 2,
        "accountName": "testuser",
        "sendTime": 0,
        "dlrTime": 2

2.5.2 DLR Error Codes

DLR Error Codes may vary across different platforms, influenced by factors such as error code mapping and other considerations.

DLR error codes are given in the following table:

Value (dec) Description
0 No error
1 Unknown subscriber
9 Illegal subscriber
11 Teleservice not provisioned
13 Call barred
15 CUG reject
19 No SMS support in MS
20 Error in MS
21 Facility not supported
22 Memory capacity exceeded
29 Absent subscriber
30 MS busy for MT SMS
36 Network/Protocol failure
44 Illegal equipment
60 No paging response
61 GMSC congestion
63 HLR timeout
64 MSC/SGSN timeout
70 SMRSE/TCP error
72 MT congestion
75 GPRS suspended
80 No paging response via MSC
81 IMSI detached
82 Roaming restriction
83 Deregistered in HLR for GSM
84 Purged for GSM
85 No paging response via SGSN
86 GPRS detached
87 Deregistered in HLR for GPRS
88 The MS purged for GPRS
89 Unidentified subscriber via MSC
90 Unidentified subscriber via SGSN
112 Originator missing credit on prepaid account
113 Destination missing credit on prepaid account
114 Error in prepaid system
500 Other error
990 HLR failure
991 Rejected by message text filter
992 Ported numbers not supported on destination
993 Blacklisted sender
994 No credit
995 Undeliverable
996 Validity expired
997 Blacklisted receiver
998 No route
999 Repeated submission (possible looping)

Delivery error codes are very often unreliable because of a lack of standards in messaging protocols. Bulk Service tries to provide the best effort to unify error code values. Error codes returned by underlying routes are mapped to the above table.

2.5.3 Delivery Report Events

Delivery events that HORISEN Bulk Service sends to the Callback are:

Name DLR mask value Description
DELIVERED 1 Delivered to phone, final status.
UNDELIVERED 2 Non-Delivered to Phone, final status.
BUFFERED 4 Queued on SMSC, temporary status.
SENT_TO_SMSC 8 Delivered to SMSC, temporary status.
REJECTED 16 Non-Delivered to SMSC, final status.

Statuses described with 'final status' are final delivery reports – no further delivery reports will be sent for the message. Statuses described with 'temporary status' are of two kinds:

  • Queued on SMSC usually means that there was some problem delivering the message to the mobile phone, and further DLRs will follow.
  • Queued on SMSC means that HORISEN Bulk Service sent the message to the destination network.

DLR Mask set for each sent message can be a combination of these values. For example, 1+2+16=19 means that all the final statuses will be reported (DELIVERED, UNDELIVERED, REJECTED). DLR Mask 19 is recommended.

Temporary statuses are not always available, and it may depend on various criteria when they can be sent.

3. Additional Tables

3.1 GSM Character Set

Dec 0 16 32 48 64 80 96 112
Hex 0 10 20 30 40 50 60 70
0 0 @ Δ SP 0 ¡ P p
1 1 £ _ ! 1 A Q a q
2 2 $ Φ 2 B R b r
3 3 ¥ Γ # 3 C S c s
4 4 è Λ ¤ 4 D T d t
5 5 é Ω % 5 E U e u
6 6 ù Π & 6 F V f v
7 7 ì Ψ 7 G W g w
8 8 ò Σ ( 8 H X h x
9 9 Ç Θ ) 9 I Y i y
10 A LF Ξ * : J Z j z
11 B Ø <ESC> + ; K Ä k ä
12 C ø Æ , < L Ö l ö
13 D CR æ - = M Ñ m ñ
14 E Å . > N Ü n ü
15 F å É / ? O § o à

Additional characters on GSM phones (in conversion to GSM character set counted as two characters):

You want to send ASCII Send the following
Character Decimal Hex Characters Hex Decimal
<ESC> e 1B 65 27 101
<FF> 10 0C <ESC> <LF> 1B 0A 27 10
[ 91 5B <ESC> < 1B 3C 27 60
\ 92 5C <ESC> / 1B 2F 27 47
] 93 5D <ESC> > 1B 3E 27 62
^ 94 5E <ESC> ^ 1B 14 27 20
{ 123 7B <ESC> ( 1B 28 27 40
| 124 7C <ESC> @ 1B 40 27 64
} 125 7A <ESC> ) 1B 29 27 41
~ 126 7E <ESC> = 1B 3D 27 61

3.2 Supported Characters in Alphanumeric Sender

When the SMS sender is alphanumeric, it can contain characters in the printable ASCII set, but depending on the destination being used some characters may not work.

The following tables give recommendations on which characters are typically supported.

3.2.1 Special Characters

Supported Not Supported
Character ASCII Code Character ASCII Code
SPACE 0×20 $ 0×24
! 0×21 @ 0×40
0×22 [ 0x5B
# 0×23 \ 0x5C
% 0×25 ] 0x5D
& 0×26 ^ 0x5E
0×27 _ 0x5F
( 0×28 ` 0×60
) 0×29 { 0x7B
* 0x2A | 0x7C
+ 0x2B } 0x7D
, 0x2C ~ 0x7E
- 0x2D
. 0x2E
/ 0x2F
: 0x3A
; 0x3B
< 0x3C
= 0x3D
> 0x3E
? 0x3F

3.2.2 Supported Letters and Digits

  • 0123456789
  • abcdefghijklmnopqrstuvwxyz