SMS HTTP(S) API v5.0.4

1. Introduction

The HTTP Service API is designed for the Short Message Service (SMS). It allows customers to send and receive SMS over HTTPS. This document provides the technical specifications for the service, ensuring efficient message transmission and status monitoring.

1.1 Overview of HTTP Bulk Service API

The HTTP Bulk Service API allows customers to:

• send SMS MT (Mobile Terminated) messages,
• access Delivery Reports (DLRs) for effective tracking of message status,
• and receive SMS MO (Mobile Originated) messages.

The API offers a comprehensive set of functionalities for enhanced message delivery and customization:

• Message Formatting: Supports various message types, including concatenated messages (long texts) and WSI (WAP Service Indication) messages.
• Special Messages: Allows for the transmission of flash messages and binary messages.
• Scheduling: Provides the capability for scheduling message delivery.
• User Data Header (UDH): Enables the customization of the UDH.
• Delivery Reports (DLRs): Facilitates efficient status monitoring by allowing the direct retrieval of DLRs via HTTPS.

1.2 Handling and Billing of Long Messages

If a submitted message exceeds the allowed length, the HTTP Bulk Service API will either divide it into multiple SMS segments or send it as one segment.

Billing is always calculated based on the number of individual SMS segments required for transmission, as the segment is the billable unit for the Short Message Service.

Therefore, while a single long message (known as a concatenated SMS) may appear seamless to the recipient, the user's account is charged per segment.

1.2.1 SMS Segment Defined

A single SMS segment is the billable unit for the Short Message Service and is defined as a message of 140 bytes, which corresponds to the following character limits:

Encoding Type	Character Limit	Description
GSM 03.38	160 characters	Special characters from the GSM extension tables count as two characters.
UCS‑2 (Unicode)	70 characters	Used when any non-standard character (e.g., emoji, non-Latin script) is present.

Note on UDH (User Data Header):
The limits above apply to a segment without a UDH. A UDH is automatically added to each segment of a long (concatenated) message, which slightly reduces the available character count per segment to accommodate concatenation data. UDH specifics are governed by GSM specifications.

2. Authentication

Authentication for SMS HTTP API method calls is supported via two methods, depending on the customer's account settings:

• Using an API key
• Using an OAuth2 token

2.1 Authentication using API Key

An API key can be created in the account settings section of the user interface. The key consists of a 128-character string. To authenticate API calls, include the key in the HTTP request using the X-API-Key header.

Example:

X-API-Key: 5VMhFFYKX3EimhyJTR4iMrSHt…5knlOGBavonWaoPC03Zup

In the case that authentication fails, an error is returned.

When API Key is not valid:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store

{ 
    "error": "invalid_key", 
    "error_description": "Unknown API-KEY." 
}

When API Key is missing:

HTTP/1.1 401 Unauthorized 
Content-Type: application/json 
Cache-Control: no-store

{
    "error": "missing_key", 
    "error_description": "Unknown API-KEY." 
}

2.2 Authentication using OAuth2 token

An OAuth2 token is generated by accessing the URL:

https://sms.example.org/bulk/v5/token

The client sends a POST request to the URL with these www-urlencoded parameters to obtain a temporary token:

• grant_type with value client_credentials
• client_id with client identification received from the service provider
• client_secret with client secret received from the service provider

Example:

grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx

Authentication responds with JSON object:

HTTP/1.1 200 OK 
Content-Type: application/json 
Cache-Control: no-store

{
    "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3", 
    "token_type":"Bearer", 
    "expires_in":3600 
}

Requests to other endpoints then must have this access token in the Authentication header:

Authorization: Bearer MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3

In the case that authentication fails, an error is returned:

HTTP/1.1 401 Unauthorized 
Content-Type: application/json 
Cache-Control: no-store

{
    "error": "invalid_client", 
    "error_description": "Unknown client ID or secret."
}

For the full list of possible error values, please check the detailed description on www.oauth.com/oauth2-servers/access-tokens/access-token-response documentation page.

2.2.1 Validity of the token

Each token expires after 3600 seconds, requiring a new one to be requested. If you request a new token before the previous one expires, both remain valid until their respective expirations.

This accommodates distributed applications where not all nodes can receive an updated token immediately. A maximum of five active tokens is allowed at once; requesting more will remove the oldest, keeping only the latest five valid.

3. Sending the single SMS

This chapter outlines the supported categories of bulk SMS messages, detailing the corresponding data flow for both message transmission and delivery reports. Additionally, it presents an overview of the various scenarios pertaining to message delivery status.

3.1 Types of bulk messages

Customers can send different types of messages:

• GSM text messages
• Unicode text messages
• WAP Service Indicators (WSI)
• Binary messages

3.2 Submitting SMS

Messages are transmitted using the POST HTTP method to a designated URL. The platform's URL, along with the necessary credentials are provided by the service provider.

3.2.1 Example of submission URL

https://sms.example.org/bulk/v5/send

Please use the URLs provided by the service provider instead of "sms.example.org".

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

3.2.2 JSON fields in the submitted message

The JSON for message submission includes the following fields:

Name	Type	Mandatory?	Description
type	string	No	Type of a message. It can be text, binary or wsi. Default is text.
sender	string	Yes	SMS originator address, numeric or alphanumeric. The alphanumeric sender shown on a mobile phone can be up to 11 characters, but the API does not enforce this limit since suppliers may accept longer addresses or apply their own rules.
senderTon	int	No	Sender TON (Type Of Number), 0-255.
senderNpi	int	No	Sender NPI (Numbering Plan Indicator), 0-255.
receiver	string	Yes	SMS destination address, numeric. Recipient phone number in international format (E.164) without the leading plus sign (+). Example: "receiver": "4179123456".
receiverTon	int	No	Receiver TON (Type Of Number), 0-255.
receiverNpi	int	No	Receiver NPI (Type Of Number), 0-255.
text	string	Yes for type=text	Message text, mandatory for dcs=gsm or ucs.
dcs	string	No	Data coding scheme, gsm, ucs or auto. Used when type=text. Default is gsm.
url	string	Yes for type=wsi	URL for WSI message, mandatory for type=wsi.
title	string	Yes for type=wsi	Title, mandatory for type=wsi.
bytes	string	Yes for type=binary	Bytes of binary message in hex format, mandatory for type=binary.
dlrEvents	string	No	Represents list of the DLR events customer wants to receive. Default is: DELIVERED,UNDELIVERED,REJECTED. Supported delivery events are listed in section 3.5 Delivery Reports (DLR).
dlrUrl	string	No	URL where to send DLR webhooks (optional, if not present, the one set in an account setting in the platform is used).
dlrMethod	string	No	Method for receiving delivery reports. Possible values: webhook or query. Default is webhook.
dlrType	string	No	individual (default) or summary.
flash	boolean	No	Is the SMS flash? A flash SMS is a message that appears directly on a mobile screen for immediate viewing and then disappears, without being stored in the inbox.
validity	integer	No	SMS validity period, which is the duration in seconds during which delivery will be attempted.
scheduled	string	No	Schedule delivery of the SMS to the given time. Until this time message will be held inside SMS Platform and not sent to the suppliers. Value is given in RFC3339 format.
custom	object	No	Custom JSON object that will be sent back as a part of each DLR (optional, default empty).
udh	string	No	UDH of the SMS, represented as the array of bytes. If concatenation is required, the final UDH will include both the specified UDH and concatenation information.
serviceType	string	No	Optional service type to pass to the supplier if possible (max 6 ASCII characters).
tlv	list of objects	No	List of SMPP TLV objects (tag and value in hex strings). Transferred to the supplier only if they are connected using SMPP.

3.2.3 DCS (Data Coding Scheme)

The Data Coding Scheme (DCS) parameter specifies the encoding type for the SMS payload. The API supports the following encoding values:

Value	Encoding Standard	Description
gsm	GSM extension table (Default)	Uses the standard 7-bit GSM alphabet, which is suitable for most Latin-based languages and minimizes segment size.
ucs	UTF-16	Applies UTF-16 encoding. This is necessary for complex characters (e.g., Chinese, Japanese, and certain extended Latin sets), but each character typically requires two or more bytes.
auto	Automatic Selection	Allows the system to automatically select the most appropriate encoding between gsm and ucs based on the message content.

The chosen encoding impacts the number of SMS segments required to deliver content to a mobile device. With GSM encoding, the maximum length for a single-part message is 160 characters (noting that extension table characters count as two) and is further reduced if User Data Header (UDH) is included. Messages exceeding this limit are segmented into parts of 153 characters each, less space used by UDH. The default encoding is gsm unless specified otherwise via the optional dcs field in JSON.

The SMS HTTP API provides an additional auto value, permitting automatic selection of either gsm or ucs to minimize the total number of SMS segments sent. The chosen encoding will be indicated in the dcs field of the delivery report.

Important: If ucs coding cannot fit into a single SMS, it may use more SMS segments than gsm. Customers are charged per SMS segment by the platform. See section 5. Billing customers for sent messages.

3.2.4 Service type

If this optional field is set, its value will be sent to the supplier when the supplier is connected via SMPP. The value will appear in the service_type field of the submit_sm PDU sent to the supplier. It can contain up to 6 ASCII characters.

Example:

"serviceType": "svc0"

The "svc0" value in this example is just an example; the meaning of serviceType values can vary based on the supplier.

3.2.5 UDH field

The UDH field can be configured to include various types of User Data Headers, not just those used for message concatenation.

For reference, please consult:

• https://en.wikipedia.org/wiki/User_Data_Header

If a message requires concatenation due to its length, the resulting User Data Header (UDH) will comprise both the UDH specified in theudh field and the relevant concatenation information.

Example:

"udh": "06050415820000"

This UDH represents special case of the SMS, sending to "the application port".

3.2.6 TLVs

TLVs are the feature of the SMPP protocol, and they are not present in the SMS delivered to the destination device. They will be transferred to the supplier only if supplier is connected using the SMPP protocol. Otherwise, they will be ignored.

TLVs are represented in the optional tlv field, using the array of JSON objects:

"tlv": [ 
    {
        "tag": "020b",
        "value": "1234" 
    },
    {
        "tag": "40cf",
        "value": "ab8973cf" 
    } 
]

Where both fields, tag and value are strings with hexadecimal content.

3.2.7 TON and NPI fields

The sender (source address) and receiver (destination address) fields support the specification of TON (Type Of Number) and NPI (Numbering Plan Indicator) when required. If these parameters are not provided in the optional fields, the SMS HTTP API will automatically detect and apply the appropriate values based on the format of the sender or receiver address.

Examples can be found later in the document, in the section 3.3.6. Messages with specified TON/NPI for sender and receiver.

3.2.8 Scheduling messages

The SMS HTTP API allows users to submit messages for delivery at a specified future time. The scheduling is set for each SMS using the scheduled JSON field, which follows the RFC3339 format. Examples include:

• 2025-10-08T14:30:00Z for a particular date and time in UTC,
• 2025-10-08T14:30:00+02:00 for a time with a two-hour offset from UTC.

Messages designated for scheduled delivery are held by the API until the indicated time. The validity period for these messages begins at the scheduled time rather than the submission time.

For further information, please consult www.rfc-editor.org/rfc/rfc3339.html documentation page.

Examples can be found in the section 3.3.7. Message with scheduled delivery time.

3.3 Examples

3.3.1 Text messages in GSM encoding

SMS to be sent is encoded in JSON document:

{ 
    "type": "text",
    "sender": "BulkTest",
    "receiver": "4179123456",
    "dcs": "GSM",
    "text": "This is a test message",
    "dlrUrl": "https://my-server.com/dlrjson.php"
}

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

3.3.2 Examples (from bash shell)

CONTENT='{
    "type": "text",
    "sender": "BulkTest",
    "receiver": "41787078880",
    "dcs": "GSM",
    "text": "This is a test message",
    "dlrEvents": "DELIVERED,UNDELIVERED,REJECTED",
    "dlrUrl": "https://my-server.com/dlrjson.php"
}'

curl -L " https://sms.example.org/bulk/v5/send" -XPOST -d "$CONTENT"

Note: Instead of "sms.example.org" please use URLs provided by the service provider.

3.3.3 Unicode messages

{
    "type": "text",
    "sender": "BulkTest",
    "receiver": "4179123456",
    "dcs": "UCS",
    "text": "This is a test message with some UTF-8 characters âçê",
    "dlrUrl": "https://my-server.com/dlrjson.php"
}

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, it must be sent as concatenated parts, Unicode messages will require more parts than GSM messages.

3.3.4 WAP Server Indication (WSI) messages

{
    "type": "wsi",
    "sender": "BulkTest",
    "receiver": "41787078880",
    "url": "https://horisen.com/en/",
    "title": "HORISEN",
    "dlrUrl": "https://my-server.com/dlrjson.php"
}

3.3.5 Binary Messages

{
    "type": "binary",
    "sender": "BulkTest",
    "receiver": "4179123456",
    "bytes": "0601000100",
    "dlrUrl": "https://my-server.com/dlrjson.php"
}

Message bytes are required to be in hexadecimal format.

3.3.6 Messages with specified TON/NPI for sender and receiver

{
    "type": "text",
    "sender": "BulkTest",
    "senderTon": 5,
    "senderNpi": 0,
    "receiver": "4179123456",
    "receiverTon": 1,
    "receiverNpi": 1,
    "dcs": "GSM",
    "text": "This is a test message",
    "dlrUrl": "https://my-server.com/dlrjson.php"
}

3.3.7 Message with scheduled delivery time

{
    "type": "text",
    "sender": "BulkTest",
    "receiver": "4179123456",
    "text": "This is a test message",
    "dlrUrl": "https://my-server.com/dlrjson.php",
    "scheduled": "2025-10-08T14:30:00+02:00"
}

3.3.8 Message with TLVs

{
    "type": "text",
    "sender": "BulkTest",
    "receiver": "4179123456",
    "text": "This is a test message",
    "dlrUrl": "https://my-server.com/dlrjson.php",
    "tlv": [
        {
        "tag": "020b",
        "value": "1234"
        },
        {
        "tag": "40cf",
        "value": "ab8973cf"
        }
    ]
}

3.3.9 Message with the custom field

{
    "type": "text",
    "sender": "BulkTest",
    "receiver": "4179123456",
    "text": "This is a test message",
    "dlrUrl": "https://my-server.com/dlrjson.php",
    "custom": { 
        "myReference": "020b", 
        "userId": 1234
    }
}

3.3.10 HTTP response when sending SMS

When a message is successfully accepted for sending, an HTTP status code of 202 is returned, along with a JSON formatted response:

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

where:

• msgId denotes the message ID, formatted as a UUID and used to reference this message in subsequent operations such as DLR.
• numParts indicates the number of message segments; if the message is sent as a single SMS, this value will be 1.

If the message is rejected, an HTTP status code of 400 Bad Request is returned with the following response:

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

The API may also return other error codes within the 5xx range. In these instances, no JSON response is provided, and the error codes adhere to standard HTTP conventions.

If there were too many requests, an HTTP status code of 429 Too Many Requests will be returned with the following response:

{
    "error": {
        "code": "105",
        "message": "Throttling error"
    }
}

3.4 Submission 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 the client's IP address is 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.
RC_UNKNOWN_MESSAGE_ID	117	When query methods do not know this message ID.
RC_AUTH_TOKEN_MISSING	121	Authorization of API key missing.
RC_AUTH_TOKEN_INVALID	122	Authorization of API key invalid.
RC_AUTH_TOKEN_EXPIRED	123	Authorization of API key expired.

3.4.1 How to handle errors

Upon receiving an HTTP status code 400 Bad Request, the customer should not resubmit the message.

3.4.2 Throttling error

If a submission results in HTTP status code 429 Too Many Requests, it is advisable to wait for one second before resubmitting the request.

3.4.3 Internal server error

If a submission returns an HTTP 5xx error, wait one minute before retrying.

3.5 Delivery Reports (DLR)

When the delivery status is updated, the API generates a delivery report (DLR). Based on the chosen method for receiving these reports, the system will either call the specified webhook URL or store the delivery status data for later querying.

3.5.1 Delivery reports sent to the customer as webhooks

To receive delivery reports as webhooks, the customer needs to specify the following:

• Set the DLR method to webhook in the account settings within the user interface, or override this by including the dlrMethod field with the value webhook in the SMS submission JSON.
• Provide a DLR webhook URL in the account settings within the user interface, or override this by specifying the dlrUrl field in the SMS submission JSON.
• Indicate which delivery statuses are required using the dlrEvents field in the SMS submission JSON. If not specified, the default is DELIVERED,UNDELIVERED,REJECTED.
• If no DLR is needed, the field dlrEvents should be empty, but still present in the JSON.
  Example: "dlrEvents": ""

Supported delivery statuses:

• DELIVERED: Message reached the phone (final).
• UNDELIVERED: Message did not reach the phone (final).
• REJECTED: Not sent to SMSC, which also means UNDELIVERED (final).
• BUFFERED: Not yet sent to SMSC; held in SMS Platform.
• SENT: Sent to SMSC, awaiting delivery report.
• PENDING: Sent to SMSC and received update from the SMSC that message is still not delivered (e.g. phone is switched off).
• ACCEPTED: Only appears when querying status if there's been no change since submission; never sent via webhook. See section 3.5.5. Delivery reports available to the customer for querying.

Statuses marked as final indicate that no further delivery reports will be issued for that specific message.

Additionally, dlrEvents may be configured as follows:

• ALL: Receive notifications for all delivery events.
• FINAL: Receive only final delivery receipt (DLR) events.
• NONE: Do not receive DLR event notifications; equivalent to an empty string.

3.5.2 Delivery types

There are two delivery types for concatenated SMS:

• Individual: Each SMS has its own status and triggers a separate webhook event to the customer.
• Summary: A single DLR covers all SMS parts and sends one webhook to the customer.

3.5.3 Example of the DLR

Delivery reports are transmitted to the customer's designated webhook URL via an HTTP POST request containing a JSON payload in the following format:

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

The preceding JSON demonstrates DLR for a message that is not concatenated (numParts is 1), with partNum set to 0.

Fields in DLR:

Name	Type	Description
msgId	string	ID of the message, the one returned when SMS is submitted.
event	string	One of defined in section 3.5. Delivery Reports (DLR).
errorCode	integer	Error code, a reason for delivery failure (check DLR error code list in the 3.5.6 DLR error codes section). Zero represents no error.
errorMessage	string	A message associated with errorCode.
dcs	string	Data coding scheme used: When SMS is sent with dcs=auto, this field indicates the actual encoding applied.
numParts	integer	Total number of concatenated parts. If message is not concatenated, then numParts is 1.
partNum	integer	A number of a message part. It can be from [0..numParts-1] interval. It is not present if the dlrType=summary.
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.
account	string	Account name.

Depending on 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 per segment (this information is informal and may be subject to change).
• currency - The currency of the price.

Each of these additional fields is assigned to a value of type string.

If an SMS is submitted with the custom field, the DLR will include:

• 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 SMS Service to required number of SMS parts. DLRs are sent to the Webhook URL for each SMS part independently.

Example of DLR with additional fields:

{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
    "event": "DELIVERED",
    "errorCode": 0,
    "errorMessage": "",
    "dcs": "gsm",
    "partNum": 0,
    "numParts": 1,
    "account": "testuser",
    "sendTime": 0,
    "dlrTime": 2,
    "mcc": "228",
    "mnc": "01",
    "country": "ch",
    "price": "0.01",
    "currency": "chf"
}

3.5.4 Example of DLRs for a concatenated message

3.5.4.1 DLR type "individual"

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

   {
       "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa5e",
       "event": "DELIVERED",
       "errorCode": 0,
       "errorMessage": "",
       "partNum": 0,
       "numParts": 2,
       "account": "testuser",
       "sendTime": 0,
       "dlrTime": 2
   }

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

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

3.5.4.2 DLR type "summary"

Example when using DLR type summary for the concatenated message of three parts:

{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa6g",
    "event": "DELIVERED",
    "errorCode": 0,
    "errorMessage": "",
    "numParts": 3,
    "partStatuses": {"DELIVERED", "DELIVERED", "DELIVERED"},
    "account": "testuser",
    "sendTime": 0,
    "dlrTime": 2
}

3.5.5 Delivery reports available to the customer for querying

Customer makes GET HTTP request to the URL:

https://sms.example.org/bulk/v5/query

with GET parameters:

• msgId - identify the message we are querying
• optionally partNum (where partNum is from the range [0..numParts-1])

For example:

https://sms.example.org/bulk/v5/query?msgId=9325d0a8-2638-11e6-afe7-bffc7cc8fa6g 
https://sms.example.org/bulk/v5/query?msgId=9325d0a8-2638-11e6-afe7-bffc7cc8fa6g&partNum=1

As a response SMS HTTP API returns a JSON object identical to the one that would be received using the webhook.

3.5.5.1 Example when using "individual" DLR type

{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa5e",
    "event": "DELIVERED",
    "errorCode": 0,
    "errorMessage": "",
    "partNum": 0,
    "numParts": 2,
    "account": "testuser",
    "sendTime": 0,
    "dlrTime": 2
}

3.5.5.2 Example when using "summary" DLR type

{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa6g",
    "event": "DELIVERED",
    "errorCode": 0,
    "errorMessage": "",
    "numParts": 3,
    "partStatuses": {"DELIVERED", "DELIVERED", "DELIVERED"},
    "account": "testuser",
    "sendTime": 0,
    "dlrTime": 2
}

3.5.6 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.
970	WAP Push Forbidden.
985	Rejected by SPAM filter.
986	FIXNET not allowed.
987	Message too long.
988	System error.
989	Supplier rejected SMS.
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 may be inconsistent due to variations in messaging protocol standards. The SMS Platform tries to standardize error code values. Error codes received from underlying routes are mapped to the table above.

4. Batches - Sending multiple SMS at once

The SMS HTTP API enables the submission of multiple SMS messages within a single HTTP request, a feature known as batch mode.

4.1 Submitting batch

Batches, consisting of multiple SMS messages, are sent to the following URL using the POST method:

https://sms.example.org/bulk/v5/sendbatch

The request requires a JSON payload with the structure specified below:

{
    "messages": [
        {
            "type": "text",
            "sender": "BulkTest",
            "receiver": "4179123456",
            "dcs": "GSM",
            "text": "This is a test message to the first receiver",
            "dlrUrl": "https://my-server.com/dlrjson.php"
        },
        {
            "type": "text",
            "sender": "BulkTest",
            "receiver": "4179123478",
            "dcs": "GSM",
            "text": "This is test message to the second receiver",
            "dlrUrl": "https://my-server.com/dlrjson.php"
        }
    ]
}

Each message in the messages array follows the same JSON format as the single SMS submission described in section 3.2. Submitting SMS.

A single batch may contain up to 10,000 messages.

Upon successful submission, the SMS HTTP API returns this response:

{
    "numMessages": 2, 
    "batchId": "60b541a8-a423-11f0-82a4-42fa039c733f", 
    "messages": [
        {
            "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f", 
            "numParts": 1 
        }
        {
            "msgId": "57a42ca0-a423-11f0-bf3d-42fa039c733f", 
            "numParts": 1 
        }
    ]
}

The returned JSON document includes:

• numMessages for the number of messages submitted
• batchId for future reference
• messages, an array of responses as defined in section 3.2. Submitting SMS.

4.2 Checking batch delivery status

When utilizing batch mode for submissions, the process for receiving DLR reports is consistent with that of individual SMS messages, as outlined in Section 3.5. Delivery Reports (DLR). Customers may receive webhooks regarding the status changes of each SMS, or alternatively, employ the query method to obtain the status of a single message.

5. Billing customers for sent messages

Customers are charged for every SMS segment transmitted. When a message surpasses the character limit permitted by the chosen data coding scheme, it is divided into multiple segments, with each segment incurring an individual charge.

6. Receiving MO Messages

Customers can receive MO (Mobile Originated) messages either via HTTP(S) webhooks or by making HTTPS queries to retrieve new messages.

6.1 Receiving MO messages as webhooks

To receive SMS MO (Mobile Originated) messages, customers must provide the service provider with a webhook URL, which should be configured in the account settings.

The customer is required to supply the following details:

• Webhook URL (HTTP or HTTPS)
• HTTP Basic Authentication credentials (username and password), if authentication is needed

Once an MO message is received for the customer, the SMS platform sends a HTTP(S) POST request to the configured webhook URL, including the JSON payload with the following fields:

Name	Description
id	Message ID (UUID format).
account	Account name.
src	Source number (sender) in the international format.
dst	Destination number (receiver) in the international format.
text	Message text.
received	RFC 3339 formatted timestamp when the MO arrived at the system.
numParts	Total number of concatenated parts. If message is not concatenated, then numParts is 1.
dcs	Data coding scheme used in the MO (gsm or ucs).
country	Country ISO2 code.
serviceType	The service type field may be included if it has been enabled in the account settings.
tlv	TLVs provided by the supplier. Optional; included if enabled in the account settings.
udh	All UDH components (Information Elements) in each received message part, excluding concatenation details. Optional; included if enabled in the account settings.

Example:

{
    "id": "d1ec69e2-bcfd-11ed-afa1-0242ac120002", 
    "account": "account1", 
    "src": "41781234567", 
    "dst": "41587000000", 
    "text": "This is an MO", 
    "dcs": "gsm", 
    "numParts": 1, 
    "received": "2006-01-02T15:04:05Z07:00", 
    "country": "CH"
}

Example with serviceType, tlv and udh:

{
    "id": "d1ec69e2-bcfd-11ed-afa1-0242ac120002",
    "account": "account1",
    "src": "41781234567",
    "dst": "41587000000",
    "text": "This is an MO",
    "dcs": "gsm",
    "numParts": 1,
    "received": "2006-01-02T15:04:05Z07:00",
    "country": "CH",
    "serviceType": "SVC01",
    "tlv": [
        {
            "tag": "020b",
            "value": "1234"
        },
        {
            "tag": "40cf",
            "value": "ab8973cf"
        }
    ],
    "udh": "06050415820000" 
}

For details regarding TLVs, please refer to section 3.2.6 TLVs.

6.2 Receiving MO messages using query method

This method replaces webhooks. Customers send an authenticated HTTPS GET request to

https://sms.example.org/bulk/v5/query-mo

using the same authentication as SMS MT calls described in section 2. Authentication.

This method retrieves a maximum of 5 received MO messages by default. If the customer prefers to adjust the number of messages returned, this can be specified via the GET parameter n:

https://sms.example.org/bulk/v5/query-mo?n=100

Maximum value of n is 10000.

This method returns a JSON payload containing the messages received:

{
    "mo": [ 
        {
            "id": "d1ec69e2-bcfd-11ed-afa1-0242ac120002", 
            "account": "account1", 
            "src": "41781234567", 
            "dst": "41587000000", 
            "text": "This is an MO", 
            "dcs": "gsm", 
            "received": "2006-01-02T15:04:05Z07:00", 
            "country": "CH"
        }, 
        { 
            "id": "0abfdec8-a830-11f0-a378-42fa039c733f", 
            "account": "account1", 
            "src": "41781234876", 
            "dst": "41587000002", 
            "text": "This is an MO to another receiver", 
            "dcs": "ucs", 
            "received": "2006-01-02T15:06:05Z02:00", 
            "country": "CH" 
        } 
    ] 
}

The array mo returns up to n messages. If there are no pending MO messages, it returns an empty array.

{
    "mo": []
}

Each received MO message is returned precisely once.

6.3 Response codes

The customer web server must respond to HTTP requests with a status code:

• Use HTTP 200 or 202 if the message has been accepted for processing.
• Any HTTP 4xx or 5xx response will be treated as a 'temporary failure', prompting the service to retry delivery of the message.

If an HTTP request fails due to network issues, the system will attempt to deliver the message again.

6.4 Handling long/concatenated MO SMS

When a mobile user submits a lengthy MO message transported as concatenated SMS, the SMS Platform aggregates all segments and transmits a single MO webhook containing the fully assembled message text.

6.5 Sending MT messages as a reply

If customer service is required to send a response in the form of an MT message, it should be transmitted via the Bulk SMS HTTP Service.

7. Additional notes

7.1 GSM character set

GSM character set is described on the following URL:

• en.wikipedia.org/wiki/GSM_03.38

(section: GSM 7-bit default alphabet and extension table of 3GPP TS 23.038 / GSM 03.38)

7.2 Supported characters in alphanumeric sender

When an SMS sender uses alphanumeric characters, it may include those from the printable ASCII set. However, compatibility with certain characters can vary depending on the destination.