About the SMS/Bulk SMS API Reference

The SMS/Bulk SMS API reference contains details about available API parameters and how to interpret incoming responses. We divide the information into the following sections:

  • Endpoints – A list of all available endpoints for the SMS/Bulk SMS API, and the methods you can use with them.
  • SMS and Bulk SMS Endpoints – The SMS and Bulk SMS endpoints  use the same request and response parameters, except the Bulk SMS endpoint can handle multiple phone numbers.
  • Callback Query Parameters – Use callback query parameters to retrieve information about a sent SMS.
  • Message Delivery Statuses – Check the status of messages in delivery reports against the chart provided here.

If you want example use cases, please see the SMS/Bulk SMS Use Cases page.

To exchange SMSes using SMPP, please see the SMPP Specification page.

Endpoints

The Mitto SMS and Bulk SMS APIs work with different endpoints, but the same parameters apply to either.

Mitto recommends using geo-resolve endpoints for best results. This will ensure the best possible connection latency wherever you send requests from.

Location Endpoint
Frankfurt, Germany https://rest-fra.mittoapi.net
Singapore https://rest-sgp.mittoapi.net
Hong Kong https://rest-hkg.mittoapi.net
United States https://rest-useast.mittoapi.net

If you don’t want to choose a geo-resolved endpoint for some reason, you can also use https://rest.mittoapi.net

For the Mitto SMS API endpoint, you send a POST request to:
https://<base endpoint>/sms

For the Mitto Bulk SMS API endpoint, you send a POST request to:
https://<base endpoint>/smsbulk

If you plan to use delivery reports, the URL is specified by you, and whitelisted by Mitto.

For the conversion tracking endpoint, you send a POST request to:
https://rest.mittoapi.net/sms/converted

For the usage by country endpoint, you send a POST request to:
https://rest.mittoapi.net/usage/bycountry

SMS and Bulk SMS Endpoints

This section provides details about request and response parameters for SMS and Bulk SMS. They are the same for either API. For examples, see the SMS/Bulk SMS Use Cases page.

Request Parameters

This tables explains the parameters for the MITTO SMS and Bulk SMS API.

Parameter Name Data Type Required Description
from string yes Free-form text with which the sender identifies themselves to the recipient. This is what the recipient will see as from whom the message is. Can be a phone number, or the name of the company or the service.
Example: MITTO SMS
to string yes The number to which the message is sent. Numbers are specified in E.164 format. This parameter can accept an array of strings for bulk sms.
Example: 359898876737
text string yes The body of the SMS message.
If the message contains characters outside the range of the GSM Standard and Extended tables, then you need to set the character encoding to Unicode (type=Unicode as a query parameter). For details, refer to Long SMSs and Changing the Default Encoding of the Message.
type string no Character set in which the message body will be encoded.
If not specified, the default encoding (GSM) is used. For Unicode, set type Unicode. For Binary, set type to be Byte. For automatic detection set type to auto.
reference string no First metadata field for tagging the message. The metadata is returned in the delivery report by the callback. It can be any free-form text you consider appropriate. You can use a different reference string for each message or tag multiple messages with the same string and group them together in this way. For details, refer to Delivery Reports and Add Metadata to the Message.
Example: Spring campaign
deliveryStatusesToNotify string no
udh string no Custom Hex-encoded User Data Header.
Example: 06050415811581
validity int no Validity period of the SMS message in minutes.
When a message has not been delivered to the receiver at the first attempt, subsequent delivery attempts will be made until the validity period expires, after which the message is discarded as undeliverable.
If the specified validity period is different from the validity period of the supplier, then the shorter period is enforced.
When not specified, the validity of a message defaults to 2,880 minutes (48 hours).
pid int no Protocol identifier to use. Must be consistent with the udh parameter value.
When not specified, defaults to 0.
flash boolean no When set to true it will send the message in Flash mode
test boolean no When set to true, the API call is in test mode and no actual SMS is delivered. The response returns “test”: true. For test calls, there is no id parameter in the response. When set to false, you make the API call in production mode. The system delivers an SMS, and returns the id parameter in the response.
If you don’t use this parameter, by default you make the API call in production mode.
callback string no When used, it overrides the URL address set on the account. For more details see the use case “Replace Callback URL in API Call.”

Response Parameters SMS/Bulk SMS API

This table explains the response body parameters of MITTO SMS API.

Parameter Name Always Returned Description
id no ID string of the SMS message. When the length of the body text of the message exceeds the limit, then several concatenated are send to the receiver and in that case only id of the first message is returned.
Not returned when making a test call or when error occurs.
timestamp no Timestamp of the SMS message in ISO 8601 format.
Example: 2019-04-13T17:51:06.3091182Z
For a description of the format, refer to Date and Time Formats page of the W3 Consortium.
responseCode no A number showing the status of the request. Value of 0 means that the call was successful call, any other value indicates an error.
For details, refer to Status Codes.
responseText no Text describing the responseCode.
For details, refer to Status Codes.
textLength no Length of the sent text.
test no When “test”: true, indicates a test API call. (No actual SMS sent.)
When not present or when “test”: true, an actual SMS message has been sent.

Status Codes

The SMS/Bulk SMS API supports these status codes and their descriptions in the responseCode and responseText parameters of the response body.

Status Code Status Code Description How to fix?
0 SMS sent
1 Internal error Contact Mitto support.
2 Invalid type Please specify the type parameter. Allowed types include GSM, Unicode, Binary, and auto.
3 Empty message The text parameter is empty. It cannot be empty, so this error is returned if it is.
4 Message text is invalid Make sure the text parameter of the request does not contain any characters that are not supported by the encoding set specified in the type parameter.
5 Empty sender Set the from parameter.
6 Invalid sender The alphanumeric sender ID length should be between 3 and 11 characters. Numeric sender ID length should be between 3 and 14 characters.
7 Empty receiver Please specify a receiver number.
8 Invalid receiver Verify the value of the to parameter of the request contains only numbers in E.164 format.

Callback Query Parameters

These are the Callback API parameters with which you can retrieve information about a sent SMS. Both GET and POST methods are supported. The string template for the API supports angle brackets (< and >), as well as the dollar sign ($) as delimiters.

Status Code Description
msgid Message ID
sendtime Time when message was sent
status Delivery status
receiver Receiver of the message
mcc Mobile country code (by spec)
mnc Mobile network code (by spec)
cost Cost in 1/100 of the billing currency (e.g. 1.4 for 0.014 EUR)
errorcode Error code – see Delivery Report Error Codes section.
sendtimestamp Delivery time of the message in UNIX format.
reference Content of the reference parameter as specified at sending the SMS

Delivery Report Error Codes

If you set up callbacks, Mitto provides more extensive error codes. Error codes that can appear in responses include:

Status Code Description Explanation
0 No Error No Error
1 Unknown subscriber The MSISDN is inactive or no longer active
2 Unknown subscriber – NR Changed Fault in Number Portability of the MSISDN of the range holder. In certain countries, this occurs more frequently if a number was ported multiple times.
5 Unidentified subscriber This occurs when the mobile switching center (MSC) that a message was sent to is not aware of the subscriber international mobile subscriber identity (IMSI). It suggests the home location register (HLR) was not updated or there was an MSC malfunction.
6 Absent subscriber for SMS Absent subscriber for the subscriber handset is not available for the SMS service.
7 Unknown equipment The system rejected the message because the subscription handset was not identified.
8 Roaming not allowed The system rejected the message due to failed authentication or filtering (roaming scenario).
9 Illegal subscriber The system rejected the message due to failed authentication or filtering.
10 Bearer Service not provisioned The system rejected the message due to subscription not supporting SMS
11 Teleservice not provisioned The system rejected the message due to subscription not supporting SMS
12 Illegal equipment The system rejected them message because the subscription handset or network does not support SMS
13 Call barred The system rejected the message due to subscription or network not allowing SMS
21 Facility not supported Rejection due to subscription not supporting SMS
27 Absent subscriber The subscriber handset is not logged onto the network due to it being turned off or out of coverage
28 Incompatible MS terminal error The system rejected the message due to the requested facility not being supported by the mobile user terminal.
31 Subscriber busy for SM MT The subscriber handset is not currently available for SMS delivery.
32 Equipment failure The receiving handset does not support SMS or an SMS feature
33 MS memory capacity exceeded The receiving handset does not have the memory capacity to receive the message
34 GSM system failure The MSC rejected the message due to an SS7 protocol or network failure
35 GSM Data Error – data missing GSM Data missing
36 GSM Data Error GSM Wrong data
45 Subscriber busy The subscriber is currently not able to perform GSM operations
100 Internal SMSC error Internal Short Message Service Center (SMSC) error
101 Internal SMSC error Internal SMSC error
103 Unspecified GSM error Unspecified Global System for Mobile Communications (GSM)
104 Unspecified GSM error Unspecified GSM error
105 Unspecified GSM error Unspecified GSM error
150 Receiver SRI timeout Subscriber Remote Interface Technology (SRI)
151 Receiver SM FW timeout Receiver SM FW timeout
600 Destination not available The destination is not available on your account, please contact your account manager
601 Credit limit Credit limit reached, please contact your account manager
602 Subscriber flood protection Multiple identical submission threshold reached
603 Invalid source address Invalid length or type of Telecommunications Private Operating Agency (TPOA)
604 Invalid destination address Invalid length or type of Mobile Station International Subscriber Directory Number (MSISDN)
605 Unknown destination address The receiving number is not mobile or the system failed to determine the destination network
606 No matching prefix found An internal routing error occurred, caused by an unrecognizable MSISDN prefix. Please contact Mitto support
800 Internal routing error An internal routing error occurred, please contact Mitto support
801 External routing error An error occurred during interworking with an external SMSC partner
999 Unspecified error Unspecified error

Statuses for Delivery Reports

The API returns these statuses and descriptions in the delivery reports.

States Description
SENT The message was sent to the mobile network.
DELIVERED The message was delivered.
UNDELIVERED The message is undeliverable. (Possibly because the device is unavailable for more than 48 hours or the phone number is wrong.)
BUFFERED The message is buffered in the SMSC because the device is not available; re-delivery possible in the next 48 hours.
FAILED The message delivery was rejected by the carrier.
EXPIRED The message could not be delivered within the defined validity period.

Enable 2-Way SMS

This section explains how to enable 2-way communication and provides details about the request and response parameters. To enable 2-way communication, do the following:

  1. Request a dedicated number from Mitto. Ask your account manager.
  2. Enable a webhook service that can receive HTTP forwards from the Mitto platform.
  3. Provide a URL address to your account manager where HTTP forwards will be sent. This address must be whitelisted on Mitto’s side.

 

Request Parameters

Parameters Data Type Required Description
coding string no Use this to select the character set in which the message content will be encoded.
sender string yes This represents the sender number from which the message is sent.
content string yes Use this to add the content of your SMS message.
receiver string yes This represents the receiver number to which the message is sent.
msgid string yes The unique ID string for retrieving the message.

Conversion Tracking

This section provides information about how to enable conversion tracking. Conversion tracking allows you to track delivery of 2FA messages. This provides the best possible routing options. In order to enable conversion tracking, you must contact your account manager. See the use case Enable Conversion Tracking for more details.

Conversion Tracking Parameters

Conversion tracking has only one parameter.

Parameter Data Type Required Description
messageId string yes Add the unique ID for a message for which conversion occurred.

Conversion Tracking HTTP Response Codes

HTTP Response Code Message Description
200 OK No Error
400 Bad Request Conversion rate tracking is not enabled for this customer account – a JSON string is also returned. For example: No convertible message found for id “8d19cf53-a264-4cc6-800c-95600aeb9141”
404 Not Found No message with the given messageId was found to mark as converted – a JSON string is also returned. For example: No convertible message found for id “8d19cf53-a264-4cc6-800c-95600aeb9141
429 Too many requests Too many requests within a certain timeframe.
500 Internal Server Error

Retrieve API Usage Information

You can use the Usage endpoint to retrieve details about SMSes sent within a specific time frame.

Usage Request Parameters

The table shows the parameters you can send in your request.

Parameter Name Data Type Required Description
startDate date-time yes The date you want to start retrieving usage information from. The date should be expressed according to ISO-8601 format YYYY-MM-DD or YYYYMMDD.
endDate date-time yes The date you want to stop retrieving usage information from. As with the start date, use ISO-8601 format YYYY-MM-DD or YYYYMMDD.
accountName string yes The account name tied to your API key. If unknown, please contact your Account Manager.

Usage Response Parameters

This section shows you what you will receive in a response to your request for usage information.

Parameter Name Always Returned Description
country no The country code expressed according to ISO 3166-1 Alpha-3 code format.
messagesCount no Number of messages sent per country.
cost no This is the account name tied to your API key. If unknown, please contact your account manager at Mitto for more information.

These parameters are only returned if there is any usage in the specified timeframe. The timeframe limit is 31 days. If exceeded, the following will be returned: “error”:”Maximum queryable period is 31 days”