Table of Contents
Synopsis
This API function sends an SMS containing message text from the specified account and sender number to a recipient’s phone number. If the carrier allows masking the sender with some brand or string, the sender mask can be set in the API. The sender mask is limited to 11 characters beyond which it will be cut-off. 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 to be passed inside the “campaign-ref” node.
Request: JSON
curl -X POST \
-H "x-api-key: API_KEY" \
-H "content-type: application/json" -d '
{
"action": "sendsms",
"message-text": "MESSAGE_TEXT",
"to": "RECEIVER_PHONE_NUMBER_WITH_COUNTRY_CODE",
"from": "SENDER_NUMBER",
"from-mask": "SENDER_MASK",
"campaign-ref": "CAMPAIGN_REFERENCE",
"click-tracking": true/false
}' \
"API_ENDPOINT_URL"
Success Response: JSON
{
"status": "Success",
"tracking-id": "TRACKING_ID_OF_REQUEST",
"to": "RECEIVER_PHONE_NUMBER_WITH_COUNTRY_CODE",
"from": "SENDER_NUMBER",
"status-details": "SMS request accepted and queued for delivery"
}
Failure Response: JSON
{
"status": "Failure",
"error-code": "ERROR_CODE",
"error-info": "ERROR_INFO",
"to": "RECEIVER_PHONE_NUMBER_WITH_COUNTRY_CODE"
}
Request Parameters
Param Name | Optional/Mandatory; Datatype | Description |
x-api-key | Mandatory; Alphanumeric | Authentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive. |
action | Mandatory; String | Explains the action for this API Request. Value is Case-Insensitive. |
message-text | Mandatory; String | SMS message text. Character limits are 160, 140, 70 characters for GSM, UTF-8, Unicode respectively. Messages above the limit are concatenated and billed as multiple messages. |
to | Mandatory; String | Destination phone number with country code. |
from | Mandatory; String | Shortcode, or Toll Free or 10 DLC with country code. |
from-mask | Optional; String | Only carriers in certain countries allow Alphanumeric senders. Not supported in the USA. |
campaign-ref | Optional, Mandatory only if the “Enforce Campaign Check” is enabled on the account requiring a number to be actively subscribed; String | The campaign reference for which the number is subscribed into. |
click-tracking | Optional, by default we send the message as is without replacing it with any short link; Boolean | true = Any link or URL in the SMS will be replaced with the auto generated short links. Total number of clicks for each link will be tracked and counted in our database. false = Links or URLs in the SMS will be sent as is without any replacement. |
Response Parameters
Param Name | Presence | Description |
status | Always | “Success” or “failure”. |
status-details | Success response only | More details about the status. |
tracking-id | 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. |
from | Success response only | Shortcode, or Toll Free or 10 DLC with country code. |
error-code | Error response only | Error code associated with the error. |
error-info | Error response only | Error message explaining the error code. |
Request Examples
Example 1:
curl -X POST \
-H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "content-type: application/json" -d '
{
"action": "sendsms",
"message-text": "This message is sent for testing purposes only.",
"to": "+10000000001",
"from": "00000"
}' \
"API_ENDPOINT_URL"
Example 2:
curl -X POST \
-H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "content-type: application/json" -d '
{
"action": "sendsms",
"message-text": "Visit https://www.fakeurl.com/ for more info.",
"to": "+10000000001",
"from": "00000",
"from-mask": "Dunder Mifflin",
"campaign-ref": "campaign2345",
"click-tracking": true
}' \
"API_ENDPOINT_URL"
Response Example: Success
{
"status": "Success",
"tracking-id": "xxxxxxxxxxxx",
"to": "+10000000001",
"from": "00000",
"status-details": "SMS request accepted and queued for delivery"
}
Response Example: Failure
{
"status": "Failure",
"error-code": "E111",
"error-info": "Invalid Sender.",
"to": "10000000001"
}