Tutorials

MYtxtBox Quick Send API is an HTTP API that allows you to integrate the power of SMS into any mobile or web application, to quickly send SMS messages.

For example you can integrate the API into an e-commerce system to send messages to customers.

SMS Example: Dear Kojo, enjoy up to 50% discount on all Leather Bags. Use  coupon code FIFTY-OFF to checkout. http://www.dawunisboutique.com.

Screenshot-psd

Quick Send SMS API

http://api.mytxtbox.com/v3/messages/send?From=Dawunis&To=254XXXXXXXXX&Content=Hello%2CWorld&ClientReference=1234&ClientId=btgpchyh&ClientSecret=gafzdfso&RegisteredDelivery=true

Step 1

Create API Key

Before you can use MYtxtBox Quick Send API you need to have an API access key on your account. The following explains how to create your API key.

Create a MYtxtBox Account if you don’t have one. In case you have an Account go to Step 2.

Step 2

  1. Login to MYtxtBox Dashboard.
  2. Click on API at the top right menu bar to generate your API keys.

mytxtboxapiscreenshots-api-click

     3. Copy your Client ID and Client Secret for future purposes.

Step 3

A Quick PHP Example

 <?php
 
 $contacts = array(
 "233XXXXXXXXX" => "John",
 "233XXXXXXXXX" => "Baptist",

 );
 
 foreach($contacts as $number => $name){
 $url = "http://api.mytxtbox.com/v3/messages/send?".
 "From=Dawunis"
 ."&To=$number"
 ."&Content=".urlencode("Dear $name, enjoy a up to 50% discount on all Leather Bags. Use coupon code FIFTY-OFF to checkout. http://www.dawunisboutique.com.")
 ."&ClientId=btgpchyh"
 ."&ClientSecret=gafzdfso"
 ."&RegisteredDelivery=true"; 
 $curl = curl_init();

 curl_setopt_array($curl, array(
 CURLOPT_URL => $url,
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_CUSTOMREQUEST => "GET",
 ));

 $response = curl_exec($curl);
 $err = curl_error($curl);

 curl_close($curl);

 if ($err) {
 echo "cURL Error #:" . $err;
 } else {
 echo $response;
 }
 }
?>

Placeholders Description

The following parameters available for the query string.

Parameter Description Required
From The sender address or sender of the message. It can be a mobile number 233247064786 or an alphanumeric string. Yes
To The recipient telephone number eg. 254247064786. Yes
Content The message you want to send to a recipient Yes
ClientId Your MYtxtBOX API Client ID Yes
ClientSecret Your MYtxtBOX API Client secret Yes
RegisteredDelivery A true or false setting to indicate a delivery report request No

Telephone Rules

Any telephone number used must be in the international telephone number format. For example +233247064786 is in the international telephone number format.

Handling Response

HTTP/1.1 201 Created
Content-Length: 116
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Mon, 12 Aug 2013 17:11:18 GMT

{
 "Status": 0,
 "MessageId": "0d225943d1844829b6a154aeb1d1671d",
 "Rate": 1,
 "NetworkId": "62001",
    "ClientReference": "1234"
}

A “Status”: 0 response indicates that the message was successfully delivered.

Response Parameters

Upon completion of the send request the API will respond with the following parameters

Parameter Data Type Description
Status Integer The status of the request.
MessageId UUID (GUID) A unique identifier for each message.
Rate Number The total cost of this message. The default rate plan is messaging credit. Users on a service postpaid plan may have the rates defined in local currency.
NetworkId String The unique ID for the mobile network a combination of MCC and MNC for this message.
ClientReference String A reference set by the client for uniquely identifying this message. The client reference will be sent as part of delivery report notifications.
Detail Dictionary Additional details that may be relevant for the request you have made.

Handling Errors

The API responds to requests with standard HTTP codes that indicate the success or otherwise of the request. Status codes in the form 2xx indicates a successful request, whereas status codes in the form 4xx indicate an invalid request. The API will return additional error information where necessary in the response payload. The subcode is contained in the API response object as the Status field. Status codes in the form 5xx indicate an error on our side. These errors will alert our platform engineers and should be resolved within a very short timeframe.

Response Parameters

The following are response parameters.

Code Subcode Description
200 The request was successfully handled by the API.
201 0 The request was successful, and the messages has been sent for onward delivery.
100 General invalid request. Returned when no data is sent or a malformed request is received.
1 Invalid Destination address received. The phone number recipient is not a valid phone number.
2 Invalid Source Address was sent. You need to be aware of the sender address restrictions.
3 The message body was too long.
4 The message is not routable on the MYtxtBox gateway.
400 5 The delivery time specified was not a valid time.
6 The message content was rejected or is invalid.
7 One or more parameters are not allowed in the message. Details will be provided as part of the response.
8 One or more parameters are not valid for the message. Details will be provided as part of the response.
401 The request authorization failed.
402 Your account does not have enough messaging credits to send the message.
403 Forbidden. It means that the recipient has not given his/her approval to receive messages.
404 The specified message was not found.
500 The request failed on the server.
502 Bad Gateway.The server could not find any appropriate gateway for the request