Welcome to MTMO’s SMS API. Here, you’ll find information and guidance to help you integrate our HTTPS API into your own application.

The HTTPS API enables external systems to send SMS messages and to make SMS delivery status requests. Implementing request callbacks enables external systems to receive subscriber responses (MOs) and delivery receipts (DLRs) for sent messages in real-time instead of polling MTMO.

Account authentication credentials must be used with all API calls for connecting to the MTMO SMS Platform. Credentials can be requested from your MTMO Account Manager.

Responses will be in JSON format, and all requests use UTF-8 encoding with URL encoded values. To ensure security, the API is HTTPS only.

If successful, the response will return a JSON payload containing the Message ID of the sent SMS:

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8
{
    "message_id": "alss-a1b2c3d4-e5f67890"
}

In the case where the request contains more than one DNIS or the message was split due to being longer than 160/70 Characters (GSM/Unicode respectively), the response will be of the format:

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8
[{
    "dnis": "791003044222",
    "message_id": "5b4c46a8-8dc9-44b4-f55f-3bef56819305",
    "segment_num": "1"
},{
    "dnis": "791003044222",
    "message_id": "5b4c46a8-46bc-7ee6-4a16-7d4e5a0d14af",
    "segment_num": "2"
}]

In case of a rejected SMS, the response will return 400 (Bad Request) and the response body will contain the reason for rejection:

HTTP/1.1 400 Bad Request Content-Type: text/html; charset=UTF-8

NO ROUTES

Note: You may receive the response “NO ROUTES”. This response may mean several things. If you cannot troubleshoot the reason why you are receiving this response then please contact your MTMO Account Manager.

In the case of an authentication error, the response will return 401 (Unauthorized):

HTTP/1.1 401 Unauthorized Content-Type: text/html; charset=UTF-8 

not authorized (check login and password)

This call is used to query the status of an already sent SMS message.

We recommend setting up a DLR callback to receive delivery information in real-time rather than polling using this call.

If the query request is successful, the request will return a JSON payload containing one of the following possible values:

On success, the response will be similar to:

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8  
{   
  "status": "DELIVRD",
  "delivery_time": "1807161404",
  "mccmnc": "250002"
}

Where delivery_time is from the vendor in the format YYMMDDHHMM (if not provided from the vendor then the field will be blank) and mccmnc is the Mobile Country Code / Mobile Network Code as per the E.212 Standard.

Query requests can be made up to 48 hours after sending an SMS message.

In the case where the message corresponding to the queried message_id is not found, the response body will contain the error description in the status field:

HTTP/1.1 200 OK Content-Type: text/html; charset=UTF-8 
{
  "status":"message ID alss-some-message-id not found"
}

In case of an incorrect query request, the response will return 400 (Bad Request) and the response body will contain the reason for rejection:

HTTP/1.1 400 Bad Request Content-Type: text/html; charset=UTF-8 NO ROUTES

In the case of an authentication error, the response will return 401 (Unauthorized):

HTTP/1.1 401 Unauthorized Content-Type: text/html; charset=UTF-8 not authorized (check login and password)

The DLR callback function is designed for you to receive Delivery Receipts from your submitted messages in near real-time from the MTMO system. All data will be sent in application/x-www-form-urlencoded format.

To set-up DLR Callbacks, please provide your MTMO Account Manager with an URL endpoint that you wish to receive DLRs on.

Status Values

The callback payload will contain one of the following Status values:

Sample Callback

Content-Type: application/x-www-form-urlencoded 
msgid=311ab8fe32&state=DELIVRD&reasoncode=000
&to=61401123887&time=2020-02-05Z00%3A09%3A00
&mcc=505&mnc=002

The MO callback function is designed for you to receive subscriber (MO) messages in real-time from the MTMO system. All data will be sent in application/x-www-form-urlencoded format.

To set-up MO Callbacks, please provide your MTMO Account Manager with a URL endpoint that you wish to receive DLRs on. You will need to lease a number from us to receive MOs on.

MO messages over 160 characters in length, will be returned in parts and will need to be re-compiled using the SAR parameters: “sarId”, “sarPartNumber” and “SarParts”. If the message is 160 characters or less then these fields are not populated and instead return a placeholder.

Short MO sample

Content-Type: application/x-www-form-urlencoded 
message=11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111&to=61416676720&from=61411454900&msgid=alss-2way-5e316ba9-2bcf9eb0&sarId=$sarId$&sarPartNumber=$sarPartNumber$&SarParts=$sarParts$

Long MO Sample

Content-Type: application/x-www-form-urlencoded 
message=111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111&to=61416907820&from=61411486700&msgid=alss-2way-5e316d50-7fc94c1d&sarId=0&sarPartNumber=1&SarParts=2 

message=11111112222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222222&to=61416907820&from=61411486700&msgid=alss-2way-5e316d50-11884567&sarId=0&sarPartNumber=2&SarParts=2