Quick Send API

Send a simple message quickly using the quick send API. Call the following URL in your application.

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

Replace the placeholders with actual values.

Placeholders Description

  • From : The sender address or sender of the message. This can be a registered MYtxtBOX sender ID or telephone number. Any telephone number used must be in the international telephone number format and must be url encoded. For example +233247064786 is in the international telephone number format. However, to be used in the url, it must be encoded like this : %2B233247064786.
  • To : The recipient telephone number. Any telephone number used must be in the international telephone number format and must be url encoded. For example +233247064786 is in the international telephone number format. However, to be used in the url, it must be encoded like this : %2B233247064786.
  • Content : The message you want to send to a recipient
  • ClientId : Your MYtxtBOX API Client ID
  • ClientSecret : Your MYtxtBOX API Client secret
  • RegisteredDelivery : A true or false setting to indicate a delivery report request

Query String Options

You can add the following options to the request query string.

Name Type Description Required
RegisteredDelivery Boolean A true or false setting to indicate a delivery report request. No
ClientReference Numeric The Reference Number provided by the Client prior to sending the message No
Type Indicates the type of message to be sent. Possible values are:

  • Unset(default)
  • 0 – Text message
  • 1 – Binary message
  • 2 – Unicode based message

When the value is Unset, the system will automatically determine the type of message to be sent. Smart messages such as VCARDS and VCALS must not set this parameter but must provide the appropriate UDH

No
Udh String The User Data Header of the SMS Message being sent. Udh must be HEX string notation. No
Time Timestamp (YYYY-MM-DD HH:MM:SS) Indicates when to send the message. It also indicates when a message was sent if this is an inbound message.Notes:1.   This time stamp will be converted from local time to UTC (GMT) using the Time Zone configured on MYtxtBOX Account.2.     If you wish to use UTC, please change account TimeZone to UTC from the MYtxtBOX account settings.This parameter is required when you want to schedule the message. No
FlashMessage Boolean A true or false value indicating if this message must be sent as a flash message. No

 

Example Request

GET http://api.mytxtbox.com/v3/messages/send?From=ronnie&To=%2B233256786234&Content=Hello%2C+world&ClientReference=1234&ClientId=odfb1243ifrp&ClientSecret=rkteg3434nml&RegisteredDelivery=true

Example 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"
}

Error Codes

CODE SUBCODE DESCRIPTION
200 The API successfully handled the request.
201  0 The request was successful, and the messages has been sent for onward delivery.
400 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 gateway.
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