To authenticate with IDT Express Solutions HTTP API you need to pass your API key.
Either as header or (not so secure) via URL query parameter.
Header name:ย X-ApiKey
Parameter name:ย ApiKey
Used to send an SMS to a specific destination.
Host:ย api.engy.solutions
Url:ย /outbound/sms
Methods:ย GET , POST
Formats:ย JSON , XML
Either as query parameters (when usingย GETย ) or inย ย POSTย ย body document.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| From | string | x | The sender ID to be used for the SMS. See Sender IDs for restrictions. |
| To | string | x | The receiver MSISDN where the SMS should be sent to. |
| Text | string | x | The content of the SMS. See Text and Encoding Restrictions for further information. |
| Encoding | string | The encoding of the SMS content (Allowed values: GSM7 , Binary , UCS2 ; default: GSM7 ). See Text and Encoding Restrictions for further information. | |
| ReceiveDeliveryStatus | bool | true if you want to receive delivery status information (default: false ; a callback url has to be defined in your account to receive delivery status information). |
|
| RefId | string | An optional reference id which will be included in corresponding delivery status information callbacks. |
|
| Udh | string | The user data header in hex digits (e.g. 0605040C7242A3 ). Not required for long (concatenated) messages; texts are split automatically. | |
| Flash | bool | true if you want to send the SMS as flash message; it will be displayed instantly on the display of the target device (default: false ). |
Beside HTTP Status Codes each successful response will contain:
| Field | Type | Description |
|---|---|---|
| StatusCode | int | The status code for the call. See Status Codes. |
| MessageIds | string[] | An array containing the IDs of all messages which were generated. Willcontain > 1 IDs for long (concatenated) messages. |
A sender ID can be a phone number, short code or alpha numeric text.
The length of the phone number depends on the country restrictions, usually it is between 8 and 16 digits. For best support, we suggest you put aย +ย in front of the phone number.
The length of the short code is also depending on the country restrictions. Usually it is between 3 and 6 digits. Donโt put anyย +ย in front and only use digits!
An alpha numeric sender ID can contain letters, spaces, digits and special characters, likeย โย ,ย _ย ,ย ย &ย ,ย ,ย ,ย ย |ย ,ย ย +ย . The maximum length of an alpha numeric sender ID is 11 characters. Not every country and network support alpha numeric sender IDs and also not each special character is supported everywhere.
A default (ย GSM7ย ) encoded message can have a length of max 160 characters. If you put more characters in, the message will be split up into several parts. This kind of message is calledย long messageย orย concatenated messageย . Each part can of aย concatenated messageย can consist of 153 characters at max. This shorter amount is due to the fact, that the other 7 characters are โeaten upโ by informational bytes which tell the end user device that its aย concatenated messageย and further information, like total part count, current part count, etcโฆ
Aย UCS2ย orย Unicodeย encoded message can have a length of max 70 unicode characters (fyi, each one is worth 2 bytes). If you put more characters in, the message will be split up into several parts. This kind of message is calledย long messageย orย concatenated messageย . Each part can of aย concatenated messageย can consist of 67 characters at max. This shorter amount is due to the fact, that the other 3 unicode characters are โeaten upโ by informational bytes which tell the end user device that its aย concatenated messageย and further information, like total part count, current part count, etcโฆ
Aย Binaryย encoded message can have a length of max 140 characters/bytes. For theย Textย parameter please only use ASCII-Characters (8-bit). See Binary SMS for a vCard example.
Binaryย messages can also contain more than 140 characters/bytes and are then, similar toย GSM7ย andย UCS2ย messages, split up into multiple parts. Each part can then contain at max 134 characters/bytes.
If a message will be split up into several parts (ย concatenated messageย ) you will be charged for each part, as each part is a real SMS. If a message has been split up you can determine by examining theย messageIdsย return parameter; it will contain more than 1 ID if the message had to be split.
| Code | Description |
|---|---|
| 200 | OK โ The HTTP request was successful |
| 401 | Unauthorized โ You either did not specify an API Key, the key is invalid or your originating IP was not whitelisted in your account |
| 500 | Internal Server Errorโ We hope you never receive this; if you still will ever see this, it means that we have a temporary issue in our API and we are already working on a solution. |
| Code | Title | Description | |
|---|---|---|---|
| DEC | HEX | ||
| 000 | 000 | No error | No error / success |
| 001 | 001 | Unassigned (unallocated) number | This cause indicates that the destination requested by the Mobile Station cannot be reached because, although the number is in a valid format, it is not currently assigned (allocated). |
| 010 | 00A | Call barred | This cause indicates that the outgoing call barred service applies to the short message service for the called destination. |
| 017 | 011 | Network failure | This cause is sent to the Mobile Station if the MSC cannot service a Mobile Station generated request because of PLMN failures, e.g. problems in MAP. |
| 021 | 015 | Short message transfer rejected | This cause indicates that the equipment sending this cause does not wish to accept this short message, although it could have accepted the short message since the equipment sending this cause is neither busy nor incompatible. |
| 022 | 016 | Congestion | This cause is sent if the service request cannot be actioned because of congestion (e.g. no channel, facility busy/congested etc.). |
| 023 | 017 | Memory capacity exceeded | This cause indicates that the mobile station cannot store the incoming short message due to lack of storage capacity. |
| 027 | 01B | Absent subscriber | This cause indicates that the destination indicated by the Mobile Station cannot be reached because the interface to the destination is not functioning correctly. The term โnot functioning correctlyโ indicates that a signalling message was unable to be delivered to the remote user; e.g., a physical layer or data link layer failure at the remote user, user equipment off-line, etc. |
| 028 | 01C | Unidentified subscriber | This cause indicates that the subscriber is not registered in the PLMN (i.e. IMSI not known). |
| 029 | 01D | Facility rejected | This cause indicates that the facility requested by the Mobile Station is not supported by the PLMN. |
| 030 | 01E | Unknown subscriber | This cause indicates that the subscriber is not registered in the HLR (i.e. IMSI or directory number is not allocated to a subscriber). |
| 038 | 026 | Network out of order | This cause indicates that the network is not functioning correctly and that the condition is likely to last a relatively long period of time; e.g., immediately reattempting the short message transfer is not likely to be successful. |
| 041 | 029 | Temporary failure | This cause indicates that the network is not functioning correctly and that the condition is not likely to last a long period of time; e.g., the Mobile Station may wish to try another short message transfer attempt almost immediately. |
| 042 | 02A | Congestion | This cause indicates that the short message service cannot be serviced because of high traffic. |
| 069 | 045 | Requested facility not implemented | This cause indicates that the network is unable to provide the requested short message service. |
| 255 | 0FF | Unspecified error cause | This cause indicates that there has been an unidentified or unspecified error provided from the next hop. |
| 800 | 320 | Insufficient funds | Either no prepaid credits anymore or post-pay credit limit reached. |
| 801 | 321 | Anti-Spam rejection | This cause indicates that the message was rejected due to anti-spam protection regulations. |
| 802 | 322 | Empty message | The message was blocked due to the reason that it had no content. |
| 803 | 323 | Anti-Loop rejection | This cause indicates that the message was rejected due to anti-loop protection mechanism. |
| 804 | 324 | No route available | This cause indicates that temporary no supporting route is available. |
| 805 | 325 | Multi-Sent rejection | This cause indicates that the message was rejected due to the fact that it was sent several times in a very short time frame. |
| 806 | 326 | Invalid recipient format | This cause indicates that the message was rejected due to an invalid recipient format; e.g. invalid length. |
| 807 | 327 | Invalid sender | This cause indicates that the message was rejected due an invalid sender; e.g. wrong alpha-numeric format or invalid characters. |
| 808 | 328 | Number lookup failed | This cause indicates that the message could not be routed because the number lookup (e.g. MNP or HLR/SRI) failed or returned an unknown error. |
| 809 | 329 | Privacy | This cause indicates that the message was blocked due to privacy protection of the subscriber (e.g. when trying to send a silent message without permission) |
| 810 | 32A | Destination not covered | This cause indicates that the message was rejected because the destination network is not on the coverage list for the current account. The message will not be charged. We advise to re-check the latest coverage sheet provided by either your account manager or pricing team. |
| 811 | 32B | Invalid message length | This cause indicates that the message was rejected because the content length exploits the allowed standards (e.g. concat or wap exploits). |
| 812 | 32C | Queue full | This cause indicates that the message was rejected because the queue towards the next hop seems to be full. We advise to either retry a few seconds later or to use a backup account / gateway. This error is also typical for SIM routes where the TPS is reached over a longer period. |
| 813 | 32D | Queue on device full | This cause indicates that the incoming message queue on the handset or modem is full. Usually we will retry several times to redeliver. |
| 814 | 32E | Blocked recipient | This cause indicates that the message toward the recipient was blocked. This can have several reasons, e.g. blacklisted sender, blacklisted receiver, content filter, etc. |
| 815 | 32F | Relay route used | This indicates that a relay or backup route was taken, e.g. due to the fact that primary route was queuing or had similar capacity issues. Usually a backup or relay route is of equal or better quality as the primary route. |
| 816 | 330 | Validity Expired | This indicates that the validity period of the message was expired before the message could actually be delivered. |
| 899 | 383 | Temporary platform failure | This cause indicates that the message was rejected because we have temporary platform issue where the engineers will be working on immediately. |
In your account you can define a template of a URL to be called when new delivery status information area vailable. To the URL several parameters can be passed. Put the corresponding parameter name in curly braces, e.g.ย {MessageId}.
| Parameter | Type | Description |
|---|---|---|
| MessageId | string | The ID of the corresponding message. It is the ID returned by the initial http request. |
| MessageState | string | The state of the message. Possible values see Message States |
| ClientReference | string | The optional custom reference you passed in the original http request in the RefId parameter. |
| To | string | The receiver of the delivery status information. Usually the from parameter value of the original request. |
| From | string | The sender of the delivery status information. Usually the to parameter value of the original request. |
| SentDateTime | DateTime | The date and time when the original message has been sent. In ISO-8859 format (e.g. 2018-03-10T17:23:15Z) |
| ReceivedDateTime | DateTime | The date and time when the delivery status information was generated. In ISO-8859 format. |
| DeliveryStatusCode | string | The delivery status code which gives you also more information why a message is pending or could not be delivered. |
Remark: The values of the several parameters will be correctly URL encoded.
| Code | Description |
|---|---|
| DELIVERED | The message has been delivered to the end user device. |
| UNDELIVERED | The message could not be delivered to the end user device. |
| WAITING | The message is on itโs way to the end user device. Possible reason for this state can be that the device is temporarily turned off or the device is in an area with low coverage. |
| REJECTED | The message was rejected. Possible reason can be that some restrictions of the target country did not match. |
In this example we send a vCard.
Given a callback template defined in your account, like this:
https://myapi.example.com/dlr?msgId={MessageId}&state={MessageState}&to={To}&from={From}&received={ReceivedDateTime}
The following GET URL will be called if new delivery states are available:
Given a callback template defined in your account, like this:
https://myapi.example.com/dlr?msgId={MessageId}&state={MessageState}&to={To}&from=
{From}&received={ReceivedDateTime}&ref={ClientReference}
The following GET URL will be called if new delivery states are available:
Used to retrieve the current coverage with rates and upcoming rate changes.
Host:ย api.engy.solutions
Url:ย /account/ratesheet
Methods:ย GET , POST
Formats:ย JSON , XML
Either as query parameters (when usingย GETย ) or inย ย POSTย ย body document.
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| UserName | string | For SMPP accounts the username, for HTTP accounts leave blank. | |
| Password | string | x | For SMPP accounts the password, for HTTP accounts the ApiKey. |
| WithDestinationNames | bool | When true, the response body will contain the two additional fields country and network. Default: false |
Beside HTTP Status Codes each successful response will contain:
| Field | Type | Description |
|---|---|---|
| AccountName | string | The descriptive name of the account. |
| Currency | string | The currency for the account. |
| CurrentRates | RateSheetItem[] | An array containing the current coverage items. |
| ScheduledRates | ScheduledRateSheetItem[] | An array containing upcoming rate/coverage changes. |
| Field | Type | Description |
|---|---|---|
| Country | string | Name of the country. |
| Network | string | Name of the network. |
| MCC | string | Mobile Country Code |
| MNC | string | Mobile Network Code |
| MCCMNC | string | Mobile Country Code and Mobile Network Code |
| Rate | decimal | The current rate in the account currency. |
| Field | Type | Description |
|---|---|---|
| Country | string | Name of the country. |
| Network | string | Name of the network. |
| MCC | string | Mobile Country Code |
| MNC | string | Mobile Network Code |
| MCCMNC | string | Mobile Country Code and Mobile Network Code |
| Rate | decimal | The current rate in the account currency. |
| ValidFrom | datetime | The date and time from when on the change will be active. The format is ISO8601, e.g. โ2018-08-23T14:00:00.0000000Zโ |
