(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.data-privacy-src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-TT9ZP96');

Knowledge Base

Send SMS API V2

3 min read

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 NameOptional/Mandatory; DatatypeDescription
x-api-keyMandatory; AlphanumericAuthentication Key for your account to access API service. Unique Alphanumeric Key can be reset under your Account->API Settings. Case-sensitive.
actionMandatory; StringExplains the action for this API Request. Value is Case-Insensitive.
message-textMandatory; StringSMS 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.
toMandatory; StringDestination phone number with country code.
fromMandatory; StringShortcode, or Toll Free or 10 DLC with country code.
from-maskOptional; StringOnly carriers in certain countries allow Alphanumeric senders. Not supported in the USA.
campaign-refOptional, Mandatory only if the “Enforce Campaign Check” is enabled on the account requiring a number to be actively subscribed; StringThe campaign reference for which the number is subscribed into.
click-trackingOptional, by default we send the message as is without replacing it with any short link; Booleantrue = 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 NamePresenceDescription
statusAlways“Success” or “failure”.
status-detailsSuccess response onlyMore details about the status.
tracking-idSuccess response only Transaction ID for the request. Use it to match the postbacks received for this API request.
toAlwaysDestination phone number with country code.
fromSuccess response onlyShortcode, or Toll Free or 10 DLC with country code.
error-codeError response onlyError code associated with the error.
error-infoError response onlyError 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"
}
Go to Top