Thank you for filling out the form. One of our mobile experts will be in touch shortly to discuss your inquiry.
If you have any other questions please feel free to email us directly at info@mitto.ch
About the SMS API Reference
The 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 API, and the methods you can use with them.
- SMS Endpoints – The SMS endpoints use the same request and response parameters, except the endpoint for bulk SMS 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 Use Cases page.
To exchange SMSes using SMPP, please see the SMPP Specification page.
Endpoints
The Mitto SMS API works with different endpoints, but the same parameters apply to either.
Mitto recommends using geo-resolve endpoint https://rest.mittoapi.net for best results. This will ensure the best possible connection latency wherever you send requests from. If you don’t want to choose a geo-resolved endpoint, you can also use these:
| Location | Endpoint |
| Frankfurt, Germany | https://rest-fra.mittoapi.net |
| Singapore | https://rest-sg.mittoapi.net |
| Hong Kong | https://rest-hk.mittoapi.net |
| United States | https://rest-us.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 Use Cases page.
Request Parameters
This tables explains the parameters for the MITTO SMS and Bulk SMS endpoints.
| 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 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 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:
- Request a dedicated number from Mitto. Ask your account manager.
- Enable a webhook service that can receive HTTP forwards from the Mitto platform.
- 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”