Send SMS messages

POST

/sms/outgoing/send

sms

Submit 1 or more SMS messages to be sent by WinSMS. Maximum 1000 recipients per request.

The SMS message text can be a maximum of 918 characters long. If you are submitting a message longer than 160 characters, you should change the value of maxSegments.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://www.winsms.co.za/api/rest/v1/sms/outgoing/send' \
--header 'Content-Type: application/json' \
--data-raw '{
    "maxSegments": 3,
    "message": "Happy holidays from all at TelAmeriCorp.",
    "recipients": [
        {
            "clientMessageId": "clientId-3023",
            "mobileNumber": "27444444444"
        },
        {
            "mobileNumber": "27555555555"
        },
        {
            "clientMessageId": "clientId-3024",
            "mobileNumber": "276666666666"
        }
    ],
    "scheduledTime": "201712251430"
}'

Response Example

200 - Example 1

{
  "recipients": [
    {
      "acceptError": "",
      "accepted": true,
      "apiMessageId": 2316,
      "clientMessageId": "clientId-3023",
      "creditCost": 1,
      "mobileNumber": "27444444444",
      "newCreditBalance": 188.6,
      "scheduledTime": "201712251430"
    },
    {
      "acceptError": "",
      "accepted": true,
      "apiMessageId": 2317,
      "clientMessageId": null,
      "creditCost": 1,
      "mobileNumber": "27555555555",
      "newCreditBalance": 187.6,
      "scheduledTime": "201712251430"
    },
    {
      "acceptError": "BADDEST",
      "accepted": false,
      "apiMessageId": null,
      "clientMessageId": "clientId-3024",
      "creditCost": 0,
      "mobileNumber": "276666666666",
      "newCreditBalance": 187.6,
      "scheduledTime": null
    }
  ],
  "statusCode": 200,
  "timeStamp": "20170117054658978",
  "version": "1.0"
}

Request

Body Params application/json

maxSegments

integer

optional

Optional - The maximum GSM Encoded segment count that the message is allowed to utilise.

This defaults to 1, allowing for a maximum GSM Encoded message length of 160 characters.

The maximum value is 6, which allows for a GSM Encoded message length of 918 characters.

If you intend to send a message longer than 160 characters, this value should be specified.

>= 1<= 6

Default:

Example:

message

string

required

The SMS text to be sent.

Example:

Happy holidays from all at TelAmeriCorp.

recipients

array[object (messageRecipientDetails) {2}]

required

An array of messageRecipientDetails objects.

>= 1 items<= 1000 items

clientMessageId

string

optional

Optional - A parameter to identify an individual SMS message recipient on your system. The clientMessageId parameter is NOT saved by the WinSMS API.

The value of the clientMessageId parameter is returned in the submittedRecipientResult object of the response, allowing you to match a sent message to a returned message result status.

Example:

clientId-3023

mobileNumber

string

required

A recipient mobile number, using the international E164 (without the plus) format.

Example:

27444444444

scheduledTime

string

optional

Optional - The date and time that an SMS should be delivered. If not specified, or is set for a date/time prior to the current date/time, the SMS message will be sent immediately.

If specified, this value should have the format YYYYMMDDHHmm.

Example:

201712251430

Examples

Responses

🟢200OK

application/json

Body

recipients

array[object (messageRecipientResponse) {8}]

optional

An array of messageRecipientResponse objects

>= 1 items<= 1000 items

acceptError

string

optional

If the accepted value is false, this will contain the reason that delivery to the recipient was declined by the API. If the recipient was accepted, this value will be blank. Possible values-

Value	Description
INSUFFICIENT CREDITS	The User Account has insufficient credits to send the message
ACCOUNTLOCKED	The specified User Account is locked
TRIALNOT2SELF	Trial Account Restriction – Message not to own number. More Info
TOOLONG	The GSM 7-bit encoded message length exceeded 918 characters
BADDEST	An invalid mobile number was supplied, or the recipient has been blacklisted from receiving messages
OPTEDOUT	The recipient has opted out from receiving any further messages from the user
WASPADNC	The number is on the WASPA Do Not Contact List (DNC). If you are sending transactional messages then you can bypass the DNC list. Read this article for instructions.

Example:

BADDEST

accepted

boolean

optional

A boolean value indicating whether the API accepted the recipient for SMS delivery. This will be false If you have insufficient credits or the recipient mobile number supplied is not valid.

Example:

true

apiMessageId

integer

optional

The WinSMS Message Id assigned to the specific message recipient. This Id can be used to obtain the status of the message, and to delete the message if it was scheduled. If the API did not accept the recipient for delivery, the value will be null.

Example:

2316

clientMessageId

string

optional

If the optional clientMessageId value was specified in the recipient object for the recipient, it will be returned here. If not, clientMessageId will be null.

Example:

clientId-3023

creditCost

number <double>

optional

The number of credits deducted from your account for the SMS to this recipient.

The credit cost is based on the destination country of the recipient and the length (number of segments) of the message.

This credit cost will be reimbursed if the message is scheduled and subsequently deleted.

If the recipient is not accepted for delivery, the creditCost value will be null.

Example:

1.3

mobileNumber

string

optional

The mobile number specified as the mobileNumber value of the recipient object of the request.

Example:

27824444444

newCreditBalance

number <double>

optional

The number of WinSMS credits remaining in your account after processing this recipient.

Example:

188.6

scheduledTime

string

optional

The date and time that the message was scheduled for delivery to the recipient.

If no scheduledTime value was specified in the request, or the recipient was not accepted for delivery, this value will be null.

Example:

201712251430

statusCode

integer

optional

The http status code returned - reflected in the body for convenience

timeStamp

string

optional

The date/time the request was processed, in the format YYYYMMDDhhmmssSSS

version

string

optional

The current version of the API of the endpoint that was called

🟠400Bad Request

🟠401Unauthorized

🟠404Not found

🟠405Method Not Allowed

🟠413Payload Too Large

🟠415Unsupported Media Type

🟠422Unprocessable Entity

🔴500Internal Server Error

Modified at 2023-08-15 09:05:19

Get a list of incoming opt-out SMS messages

Send multiple different SMS messages