Skip to content

Send SMS API

Legacy documentation

This page documents the v1 XML API. It remains supported, but it is no longer the recommended integration path. New integrations should use the Send SMS API v2, which uses JSON. If you are maintaining an existing v1 integration, the information on this page is still accurate.

sendSMS

Synopsis

This API function sends an SMS containing text from the specified account and shortcode to a recipient’s mobile number. If “Enforce Campaign Check” is turned ON, then this function will require the campaign reference ID of the messaging campaign that the recipient’s phone number is subscribed into to be passed inside the campaignref node.

Request: XML

<REQUEST>
    <ACTION>sendSMS</ACTION>
    <API_KEY>apiKey</API_KEY>
    <OPERATORID>OPERATORID</OPERATORID>
    <TO>Recipient phone number</TO>
    <FROM>shortcode</FROM>
    <CAMPAIGNREF>CampaignReferenceID</CAMPAIGNREF>
    <TEXT>SMS Text message text</TEXT>
</REQUEST>

Request Parameters

Term Mandatory/Optional Description
ACTION Mandatory This is the name of the function you want to execute with the API.
API_KEY Mandatory Random key that is assigned to an account that can be used for authorization instead of USER/PASS. You can find and regenerate this key on the ‘API Settings’ page.
CAMPAIGNREF Mandatory if “Enforce Campaign Check” IS enabled. Optional otherwise. Depending on your API settings, you may be required to subscribe users to a campaign first before sending them messages. If you are required to subscribe to a user first, then a valid Campaign Reference is required. This would be the campaign reference ID (string) to which the user is subscribed.
FROM Mandatory A valid shortcode or longcode for the sender address(string). When sending to a list of many numbers using the ‘sendSavedContent’ function and if the ‘FROM’ value cannot be used for a certain country, then the system will re-write the sender address to use a valid shortcode for those numbers.
TEXT Mandatory The SMS message limit is 160 characters(string).
TO Mandatory This is the message recipient’s phone number in an international format.
OPERATORID Optional Carrier ID for the Phone Number

Response Parameters

Param Name Presence Description
STATUS Always “Success” or “Failure”.
TRACKINGID Success response only Transaction ID for the request. Use it to match the postbacks received for this API request.
TO Always Destination phone number with country code.
ERRORCODE Error response only Error code associated with the error.
ERRORINFO Error response only Error message explaining the error code.

Request Example: XML

<REQUEST>
    <ACTION>sendSMS</ACTION>
    <API_KEY>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</API_KEY>
    <TO>11111111111</TO>
    <FROM>00000</FROM>
    <CAMPAIGNREF>Campaign123</CAMPAIGNREF>
    <TEXT>Hello Jerry, Greetings from Marc</TEXT>
</REQUEST>

Response Example: Success

<RESPONSE>
    <STATUS>Success</STATUS>
    <TRACKINGID>xxxxxxxxxxxx</TRACKINGID>
    <TO>11111111111</TO>
 </RESPONSE>

Response Example: Failure

<RESPONSE>
    <STATUS>Failure</STATUS>
    <ERRORCODE>E713</ERRORCODE>
    <ERRORINFO>There is billing problem on your account</ERRORINFO>
    <TO>11111111111</TO>
</RESPONSE>

Postback Notification

When the SMS is sent we will generate a Postback notification. When we get an SMS delivery receipt we will generate another Postback notification. Not all carriers provide SMS delivery receipts. For more details please visit the SMS MT Delivery Status section of the Delivery Report Postback documentation.

General Error Codes

Code Description
E100 Invalid request. Make a valid request via GET/POST/XML with all the required variables.
E104 User Authentication Failed.
E105 This account has no API rights.
E106 You can call API every X seconds.
E107 This account has no rights to use this action.
E108 XML Parse error: $error.
E109 API not activated.
E112 IP was not whitelisted. API call rejected.
E113 Set throughput exceeded for this API action. API call rejected.
E114 Phone number is blacklisted. API call rejected.
E120 Account has reached the API request limit.
E503 Internal error.
Code Description
E110 Invalid receiver number.
E111 Invalid Sender.
E111 Invalid Sender to $country-name.
E628 Operator Not supported.
E712 The ‘text’ is required.
E713 There is billing problem on your account.
E715 Number is not subscribed in this campaign
E718 The ‘campaignref’ is required
E721 Invalid campaignref