Company

Developers

SMS API for our SMS Gateway Solution

Delivery Status Callback Templates

Request delivery Status Information

Authentication

To authenticate with IDT Express HTTP API (POST) you need to pass your API key as value in the request header, the key name to use is “X-ApiKey”

Messaging

Request

URL:	https://api.sms.idt.net/outbound/sms
Method:	POST # GET is also possible
Header:	Content-Type: application/json Accept: application/json X-ApiKey: YOUR-API-KEY # provided by IDT Express
Body:	{ "from": "IDT Express", # text sender max 11 char "to": "491712345678", # always use country code "text": "HTTP text message", # long messages will be split "encoding": "GSM7", # GSM7 or UCS2 "receiveDeliveryStatus": true, # request DLR "refId": "YourOwnRefID" # your identifier, will be in DLR }

Response

Header:	Content-Type: application/json; charset=utf-8
Body:	{ "statusCode": 0, "messageIds": ["4a57b5a9-59f8-48cc-a21e-3e29cef3d7c4"] }

DLR Callback

Given a callback URL provided by you is configured in your account, the DLR is sent to you in GET format (POST is also possible) like this:

https://myapi.example.com/dlr?msgid=4a57b5a9-59f8-48cc-a21e-3e29cef3d7c4&
state=DELIVERED&
code=000&
from=491712345678&
to=IDT%20Express&
sent=2025-03-31T17%3A23%3A10Z&
received=2025-03-31T17%3A23%3A15Z

Please find more detailed information about the API and its parameters in the pages below.

Request parameters

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, 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 provided by you has to be configured in your account to receive delivery status information).
RefId	string		An optional reference id which will be included in corresponding delivery status information callbacks.
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).

Response body

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. Will contain > 1 IDs for long (concatenated) messages.

Sender IDs

A sender ID can be a phone number, short code or alpha numeric text.

Phone Number

The length of the phone number depends on the country restrictions, usually it is between 9 and 16 digits. The country code needs to be included, the leading + is optional though.

Short Code

The length of the short code is also dependent on the country’s restrictions. Usually it is between 3 and 8 digits. Don’t put any + in front and only use digits!

Alpha Numeric

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.

Text and Encoding Restrictions

Maximum length

Default / GSM7 encoding

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…

SMS alphabet character support

The characters used in English are supported by GSM7, this applies also to the most common characters of other roman languages. Characters not included in the GSM7 alphabet need to be sent as UCS2 / Unicode for correct delivery – set parameter Encoding to UCS2 for this. The encoding is by default GSM7 and is not changed to UCS2 automatically.

You can find an overview about GSM7 supported characters here:
https://en.wikipedia.org/wiki/GSM_03.38

UCS2 / Unicode encoding

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…

Binary encoding

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.

Cost Remarks

If a message is 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.

HTTP Status Codes

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.

IDT Platform Status Codes

Code		Title	Description
DEC	HEX
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 an anti-loop protection mechanism.
804	324	No route available	This cause indicates that temporarily 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 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 you 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.
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.
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 the 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 expired before the message could actually be delivered.
899	383	Temporary platform failure	This cause indicates that the message was rejected because we have a temporary platform issue where the engineers will be working on immediately.

Delivery Status Codes

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 it is switched off or out of coverage but other reasons also might apply.
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.

Delivery Status Callback Templates

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.

Message States

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.

Example

Simple Text SMS

Request GET

				
					https://api.sms.idt.net/outbound/sms?ApiKey=YOUR-API-KEY&format=json&receiveDeliveryStatus=true&from=IDT%20Express&to=491712345678&text=HTTP%20text%20message

Response GET

				
					{
  "statusCode": 0,
  "messageIds": [
    "acd259b3-f164-4cef-8ccf-5b5d2430b5bf"
  ]
}

Request POST

				
					POST /outbound/sms HTTP/1.1
Host: api.sms.idt.net
Accept: application/json
Content-Type: application/json
X-ApiKey: YOUR-API-KEY

{
    "from": "IDT Express",
    "to": "491712345678",
    "text": "HTTP text message"
}

Response POST

				
					HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "statusCode": 0,
    "messageIds": ["4a57b5a9-59f8-48cc-a21e-3e29cef3d7c4"]
}

Long Text SMS

Request

				
					POST /outbound/sms HTTP/1.1
Host: api.sms.idt.net
Accept: application/json
Content-Type: application/json
X-ApiKey: YOUR-API-KEY

{
    "from": "IDT Express",
    "to": "491712345678",
    "text": "If you send >160 GSM7 characters you will receive more than one message id. In case the encoding is set to UCS2 this will happen if you send >70 UCS2 characters. Attention: if datacoding is unspecified, the message will be processed as GSM7 - there is no automatic encoding!"
}

Response

				
					HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "statusCode": 0,
    "messageIds": [
        "f44afb66-04d4-4d24-962c-2ad63eba3c11",
        "14483b80-e521-4065-bfea-d55e63c37007"
    ]
}

Flash SMS

Request

				
					POST /outbound/sms HTTP/1.1
Host: api.sms.idt.net
Accept: application/json
Content-Type: application/json
X-Api-Key: YOUR-API-KEY

{
    "from": "IDT Express",
    "to":"+ 491712345678",
    "text": "HTTP text message",
    "flash": true
}

Response

				
					HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "statusCode": 0,
    "messageIds": ["8b3b9415-c33b-464c-ae57-427e312435a5"]
}

Unicode Text SMS

Request

				
					POST /outbound/sms HTTP/1.1
Host: api.sms.idt.net
Accept: application/json
Content-Type: application/json
X-Api-Key: YOUR-API-KEY

{
    "from": "IDT Express",
    "to": "491712345678",
    "encoding": "UCS2",
    "text": "رسالة نصية HTTP"
}

Response

				
					HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "statusCode": 0,
    "messageIds": ["68f3740d-46f9-44d2-bcf4-a696d318ec71"]
}

Request delivery Status Information

Request

				
					POST /outbound/sms HTTP/1.1
Host: api.sms.idt.net
Accept: application/json
Content-Type: application/json
X-Api-Key: YOUR-API-KEY

{
    "from": "IDT Express",
    "to": "491712345678",
    "receiveDeliveryStatus": true,
    "text": "HTTP text message"
}

Response

				
					HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "statusCode": 0,
    "messageIds": ["3d00cd29-d9b6-4683-b424-12af6fd6da60"]
}

Callback

Given a callback template defined in your account, like this:

GET

				
					https://myapi.example.com/dlr?msgid=3d00cd29-d9b6-4683-b424-12af6fd6da60&state=DELIVERED&code=000&from=491712345678&to=IDT%20Express&sent=2025-03-31T17%3A23%3A10Z&received=2025-03-31T17%3A23%3A15Z

POST

				
					Content-Type: application/json; charset=utf-8

{
    "msgid": "3d00cd29-d9b6-4683-b424-12af6fd6da60",
    "state": "DELIVERED",
    "code": "000",
    "from": "491712345678",
    "to": "IDT Express",
    "sent": "2025-03-31T17:23:10Z",
    "received": "2025-03-31T17:23:15Z"
}

Request Delivery Status Information with Client Reference

Request

				
					POST /outbound/sms HTTP/1.1
Host: api.sms.idt.net
Accept: application/json
Content-Type: application/json
X-Api-Key: YOUR-API-KEY

{
    "from": "IDT Express",
    "to": "491712345678",
    "receiveDeliveryStatus": true,
    "refId": "YourOwnRefID",
    "text": "HTTP text message"
}

Response

				
					HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "statusCode": 0,
    "messageIds": ["854873a6-74ad-435a-ab1a-670e6207fd5b"]
}

Callback

Given a callback template defined in your account, like this:

GET

				
					https://myapi.example.com/dlr?refid=YourOwnRefID&msgid=854873a6-74ad-435a-ab1a-670e6207fd5b&state=DELIVERED&code=000&from=491712345678&to=IDT%20Express&sent=2025-03-31T17%3A23%3A10Z&received=2025-03-31T17%3A23%3A15Z

POST

				
					Content-Type: application/json; charset=utf-8
{
    "refid": "YourOwnRefID",
    "msgid": "3d00cd29-d9b6-4683-b424-12af6fd6da60",
    "state": "DELIVERED",
    "code": "000",
    "from": "491712345678",
    "to": "IDT Express",
    "sent": "2025-03-31T17:23:10Z",
    "received": "2025-03-31T17:23:15Z"
}

Account

Get Account Rate Sheet

Used to retrieve the current coverage with rates and upcoming rate changes.

Example for HTTP/Engage account – GET

				
					https://api.sms.idt.net/account/ratesheet?password=YOUR-API-KEY&format=json&WithDestinationNames=true

Example for SMPP account – GET

				
					https://api.sms.idt.net/account/ratesheet?username=YOUR-SMPP-USERNAME&password=YOUR-SMPP-PASSWORD&format=json&WithDestinationNames=true

Example output – JSON

				
					{
  "accountName": "YOUR-ACCOUNT-NAME",
  "currency": "USD",
  "currentRates": [
    {
      "country": "Germany",
      "network": "T-Mobile",
      "mcc": "262",
      "mnc": "01",
      "mccmnc": "26201",
      "rate": 0.1
    },
    ...

Request parameters

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
Fortmat	string		Choose between json or xml

Response body

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.

RateSheetItem

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.

ScheduledRateSheetItem

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”

Developers

Authentication

Messaging

Request

Response

DLR Callback

Request parameters

Response body

Sender IDs

Phone Number

Short Code

Alpha Numeric

Text and Encoding Restrictions

Maximum length

Default / GSM7 encoding

SMS alphabet character support

UCS2 / Unicode encoding

Binary encoding

Cost Remarks

HTTP Status Codes

IDT Platform Status Codes

Delivery Status Codes

Delivery Status Callback Templates

Message States

Example

Simple Text SMS

Request GET

Response GET

Request POST

Response POST

Long Text SMS

Request

Response

Flash SMS

Request

Response

Unicode Text SMS

Request

Response

Request delivery Status Information

Request

Response

Callback

GET

POST

Request Delivery Status Information with Client Reference

Request

Response

Callback

GET

POST

Account

Get Account Rate Sheet

Request parameters

Response body

RateSheetItem

ScheduledRateSheetItem

Form succesfully sent ;)

Our team is eager to talk to you! Let's continue this conversation on Whatsapp, shall we!

Tools

Products

BYOC

Solutions

Learn

Company