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
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:
- Make a Test API Call – Create a test SMS without actually sending one through Mitto’s network.
- Send an SMS – Learn how to send your first text message.
- Send a Long SMS – See how to send an SMS longer than 160 characters.
- Change the Default Encoding of a Message – Find out how to send a message in a language using a different character set.
- Add Metadata to a Message – Tag a message with metadata so you can organize it more easily.
- Send Bulk SMS – Send multiple messages with a single request.
- Replace Callback URL in API Call – Replace the callback URL you provided to Mitto with a different one (only applies to the current request).
- Retrieve Delivery Reports – Find out if your SMSes were delivered by retrieving delivery reports.
- Retrieve API Usage Information – Retrieve details about where SMSes were sent.
- Enable 2-Way SMS – Learn how to set up 2-way SMS.
- Enable Conversion Tracking – Track delivery of 2FA messages.
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:
- Get a dedicated number from Mitto. Contact your account manager for more information.
- Enable a webhook service capable of receiving HTTP forwards from Mitto’s SMS platform.
- 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"
}'