SMS/Bulk SMS Use Cases

This page provides details about available use cases for the SMS/Bulk SMS API. You can use the examples provided here to build more complex applications. The use cases described include:

For more details about the parameters and success/error codes, refer to the SMS/Bulk SMS API Reference page.

For more details about authentication, refer to the Authentication section on the SMS/Bulk SMS page.

Base endpoints are:

https://base endpoint/sms
and
https://base endpoint/smsbulk

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:

The geo-resolve endpoints available are:

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

Make a Test API Call

You can make a test API call without dispatching a message through Mitto’s network. Set the test parameter to true. To receive a successful response, you must use a real number for the to parameter. You will receive responses as though it were a real world setting, but your call will not go through to a handset. You can use this feature when you are debugging your implementation to avoid paying for additional text messages.

Request

curl -X POST \
'https://rest.mittoapi.net/sms' \
-H 'Content-Type: application/json' \
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"from": "MITTO SMS",
"to": "491725551234",
"text": "Hello, World!",
"test": true
}'

If you want the response as XML, change the URL to: https://rest.mittoapi.net/sms.xml

Response

{
"id": "7d35863fe6f44695a713d54e6ba0aeb5",
"timestamp": "2019-04-13T17:51:06.3091182Z",
"responseCode": 0,
"textLength": " 13",
"responseText": "SMS sent",
"test": true
}

Send an SMS

Send an SMS saying “Hello, World!” with the default character encoding to recipient +49 172 555 1234. Mitto sends your message from whatever number is available that has the same format as the country you are sending your message to.

Request

curl -X POST \
'https://rest.mittoapi.net/sms' \
-H 'Content-Type: application/json'\
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"from": "Mitto SMS",
"to": "41751231234",
"text": "Hello, World!"
}'

If you want the response as XML, change the URL to: https://rest.mittoapi.net/sms.xml

Response

{
"id": "715118ef01aa4480bbd67324a0459b0b",
"timestamp": "2019-04-13T12:07:57.8625574Z",
"to": "41751231234",
"responseCode": 0,
"textLength": 13
"responseText": "SMS sent"
}

Send a Long SMS

This example shows you how to send an SMS with a text body that exceeds the maximum allowed number of characters (160 for UTF-8, 70 for unicode). The text is 529 characters long and is split into 8 concatenated messages (sent as unicode), since it has only GSM characters it could also be sent with default “type” parameter. Then it would be split into 4 messages.

Request

curl -X POST \
'https://rest.mittoapi.net/sms.json' \
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"from": "MITTO SMS",
"to": "491725551234",
"text": " Due to the limitations of GSM/PDU standard, the body text of an SMS message cannot be longer than 160 characters (70 characters if the text is Unicode format). MITTO's SMS API overcomes this limitations by splitting larger messages into several smaller messages, each of which conforms to that standards. This operation is automatic and you don't have to do anything when making the API request the process is triggered automatically when the text entered in body of the SMS (the body parameter of the request) exceeds the limit.",
"type": "auto"
}'

Response

{
"id": "7d35863fe6f44695a713d54e6ba0aeb5",
"timestamp": "2019-04-14T16:55:56.2652450Z",
"responseCode": 0,
"textLength": " 529",
"responseText": "SMS sent successfully."
}

While the recipient receives several SMSes (concatenated together), you make only one API call. In the response for that call a single ID is returned:
{
"id": "7d35863fe6f44695a713d54e6ba0aeb5",
"timestamp": "2019-04-14T16:55:56.2652450Z",
"responseCode": 0,
"textLength": 123
"responseText": "SMS sent successfully."
}

Note

Concatenating the messages additionally reduces the maximum length of the body text to 153 (67 for unicode) the rest of the 7 (3) characters is used for UDH (User Data Header).

Change the Default Encoding of a Message

This example shows you how to send an SMS saying “Hello, World!” in Russian (“Здравствуй, Мир!”) with unicode character encoding to recipient +49 172 555 1234. The encoding is specified in the (type=auto) query parameter. Mitto recommends always using auto as the type. This ensures there are no problems with encoding since it will be detected automatically.

Request

curl -X POST \
'https://rest.mittoapi.net/sms.json' \
-H 'Content-Type: application/json' \
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"from": "MITTO SMS",
"to": "491725551234",
"text": "Здравствуй, Мир!",
"type": "auto"
}'

Response

{
"id": "715118ef01aa4480bbd67324a0459b0b",
"timestamp": "2019-04-13T12:07:57.8625574Z",
"responseCode": 0,
"textLength": 13
"responseText": "SMS sent successfully."
}

Add Metadata to a Message

This example demonstrates how to tag a message with metadata. You can use the tag to identify the message as belonging to a particular marketing campaign and to a particular A/B split test version of the marketing copy (text). In the request below, the message’s text is the B-version of an A/B text split sent within a campaign named “Campaign 2019-05”. The campaign and the split are tagged in the reference query parameter (reference=Campaign 2019-05, B-split message). The tag info will be returned in the callbacks for this message.

Request

curl -X POST \
'https://rest.mittoapi.net/sms.json' \
-H 'Content-Type: application/json' \
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"from": "MITTO SMS",
"to": "491725551234",
"text": "Еnjoy the stunning Spring 2019 visuals in our new gallery!",
"reference": "Campaign 2019-05, B-split message"
}'

Send Bulk SMS

Mitto’s SMS/Bulk SMS API lets you send multiple messages with a single API call. (If you include the same phone number in the list more than once, the number will receive a text message for each instance in your list.) The response you receive for your request will show a different id for each phone number you included with your request.

Request

curl -X POST \
'https://rest.mittoapi.net/smsbulk' \


-H 'Content-Type: application/json'\
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"from": "Mitto SMS",
"to": "491765410994,491765410995,491765410996"
"text": "Hello, World 123!"
}'

Response

{ "responseCode": 0,
"responseText": "SMS sent",
"messages": [
{
"id": "b47e7d4a-39d1-4e6c-a495-001501b3e626",
"timestamp": "2019-08-21T14:55:29.6488926Z",
"to": "491765410994",
"textLength": 13
},
{
"id": "9733ec48-dd12-4aca-b453-f89666379
"timestamp": "2019-08-21T14:55:29.6492142Z",
"to": "491765410995",
"textLength": 13
},
{
"id": "5e1dab53-b867-4cf1-98b7-22757d8acafc",
"timestamp": "2019-08-21T14:55:29.6492506Z",
"to": "491765410996",
"textLength": 13
} ]
}

Replace Callback URL in API Call

You can override the callback URL set for your account by sending the replacement callback URL as a parameter in your request. If you did not set up a callback URL in the first place, you can submit a callback URL as part of your request. You will receive reports at the URL you specify for the request.

Request

curl -X POST \
'https://rest.mittoapi.net/smsbulk' \
-H 'Content-Type: application/json'
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"from": "Mitto SMS",
"to": "491765410994,491765410995,491765410996",
"text": "Your appointment was scheduled.",
"callback": "https://www.example.com"
}'

Response

{ "responseCode": 0,
"responseText": "SMS sent",
"messages": [
{
"id": "b47e7d4a-39d1-4e6c-a495-001501b3e626",
"timestamp": "2019-08-21T14:55:29.6488926Z",
"to": "491765410994",
"textLength": 13
},
{
"id": "9733ec48-dd12-4aca-b453-f89666379418",
"timestamp": "2019-08-21T14:55:29.6492142Z",
"to": "491765410995",
"textLength": 13
},
{
"id": "5e1dab53-b867-4cf1-98b7-22757d8acafc",
"timestamp": "2019-08-21T14:55:29.6492506Z",
"to": "491765410996",
"textLength": 13
} ]
}

Retrieve Delivery Reports

Following are some examples of how to make delivery report requests. The string template for the API supports angle brackets (< and >), as well as the dollar sign ($) as delimiters. For details about the parameters, refer to Callback Query Parameters. You retrieve reports with a GET request to your callback URL.

GET Example

URL:
http://comp.callback.url.com?ID=~msgid~&MCCMNC=~mcc~~mnc~

http://your.callback.url.com?ID=d8d9505a-161b-4776-9efb-4939d5b02e99&MCCMNC=26201

POST Example – JSON

URL:
http://your.callback.url.com
Request Body:
{
"Id": "msgid",
"MccMnc": "~mcc~~mnc~",
"Price": "~rate~"
}

{
"Id": "d8d9505a-161b-4776-9efb-4939d5b02e99",
"MccMnc": "26201",
"Price": "6.00"
}

Retrieve API Usage Information

You can query the API to find out how much you use the Mitto SMS API to send texts by country.

Request

curl -X POST \
'https://rest.mittoapi.net/usage/bycountry.json' \
-H 'Content-Type: application/json' \
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-d '{
"startDate": "2020-04-01",
"endDate": "2020-04-15",
"AccountName": "promo_account"
}'

Response

{ "usagesByCountry": [
{
"country": "DEU",
"messagesCount": "1140",
"cost": "68.400000”
},
{
"country": "SRB",
"messagesCount": "565",
"cost": "33.900000”
}]
}

Enable 2-Way SMS

Mitto’s SMS API supports 2-way communication. In order to set up 2-way communication, you must do the following:

  1. Get a dedicated number from Mitto. Contact your account manager for more information.
  2. Enable a webhook service capable of receiving HTTP forwards from Mitto’s SMS platform.
  3. Provide a URL address to your account manager where HTTP forwards may be sent.

You can then retrieve information from the URL and respond accordingly.

Enable Conversion Tracking

You can enable conversion tracking to monitor delivery of your SMS messages. Ask your account manager to enable the conversion tracking feature. For more details, see the Conversion Tracking section.

Request

curl -X POST \
'https: //rest.mittoapi.net/sms/converted.json' \
-H 'X-Mitto-API-Key: Xdqnjeewea' \
-H 'Content-Type: application/json' \
-d '{
"messageId": "d8d9505a-161b-4776-9efb-4939d5b02e990"
}'