Send SMS API V2

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