Expand a method to see parameters and responses.

POST Send message(s) to multiple lists, as well as personal messages in batch mode If you need to send 1 message to a list of numbers, then use the parameter 'message_type': 'bulk', a… /api/v1/sendBulkSms
Request URL
POST https://app.sms.by/api/v1/sendBulkSms
If you need to send 1 message to a list of numbers, then use the parameter 'message_type': 'bulk', as in the example below, passing an array of numbers:
'delivery_list': [
    '375297777777',
    '375295555555',
 ]

If you need to send each message to a separate phone number, then use 'message_type': 'personal', transmitting each time the text of the message and the phone number:
'delivery_list': [
    {
       'phone': '375299999999',
       'text': 'personal message 1'
    },

To schedule a mailing, you can specify the mailing time via the parameter schedule_time, in format YYYY-MM-DDTHH:mm:ss

Sample api request
{
 'token': 'eyJpdiI6IjJzOFlFcXBmOUZEcGJlYzlzeFJValE9PSIsInZhbHV...',
 'callback_url': '',
 'messages': [
    { 
       'alphaname_id': '123',
       'name': 'mailing list 1',
       'message_type': 'personal',
       'schedule_time': '2024-12-31T23:59:59',
       'delivery_list': [
         {
             'phone': '375299999999',
             'text': 'personal message 1'
          },
          { 
            'phone': '375298888888',
            'text': 'personal message 2' 
         } 
      ] 
   }, 
   {
       'alphaname_id': '234',
       'name': 'mailing list 2',
       'message_type': 'bulk',
       'text': 'message text 2',
       'schedule_time': '2024-12-31T23:59:59', 
       'delivery_list': [
         '375297777777', 
         '375295555555', 
       ]
    }
 ]
}

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
callback_url query string Yes URL to which the response will be sent when the method is running in asynchronous mode
messages query array Yes Message Array (Sample Request Description)

Responses

200 — Completed successfully

{
    "uuid": "cc9c8043-8caf-11ef-b035-9e8f47954dec",
    "success": "OK"
}

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

POST Getting message statuses from mailings created by the sendBulkSms method To get information on mailings created by the sendBulkSms method, you need to use the uuid field fro… /api/v1/statusBulkSms
Request URL
POST https://app.sms.by/api/v1/statusBulkSms
To get information on mailings created by the sendBulkSms method, you need to use the uuid field from the sendBulkSms method response (this is the UUID of the request). The statusBulkSms method will return extended information on message statuses and errors, if any

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
uuid query string Yes UUID received in the response of the sendBulkSms method

Responses

200 — Completed successfully

[
    {
        "message_id": 1,
        "name": "mailing list 1",
        "alphaname_id": 1,
        "success": [
            {
                "delivery_id": 1,
                "phone": "375291111111",
                "status": "DELIVERED",
                "status_time": "2024-10-16 22:52:42.497994"
            },
            {
                "delivery_id": 2,
                "phone": "375292222222",
                "status": "DELIVERED",
                "status_time": "2024-10-16 22:52:43.379779"
            }
        ]
    },
    {
        "message_id": 2,
        "name": "mailing list 2",
        "alphaname_id": 1,
        "success": [
            {
                "delivery_id": 3,
                "phone": "375293333333",
                "status": "DELIVERED",
                "status_time": "2024-10-16 22:52:44.793377"
            },
            {
                "delivery_id": 4,
                "phone": "375294444444",
                "status": "DELIVERED",
                "status_time": "2024-10-16 22:52:43.008560"
            }
        ]
    }
]

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

POST Sending a single message /api/v1/sendQuickSMS
Request URL
POST https://app.sms.by/api/v1/sendQuickSMS

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message query string Yes Message
phone query string Yes Phone number
alphaname_id query string Yes —
show_cost query integer No Include (1 - enable, 0 - do not enable) the cost per message in the response
forwarding_message formData integer No Enable forwarding (1 - enable, 0 - do not enable). If the sent message does not receive the “Delivered” status within the specified time, it will be sent to Viber
forwarding_time formData integer No After how many minutes the forwarding will take place if it is enabled. The default is 60 minutes. Minimum 5 minutes. Maximum 60 minutes
vibername_id formData integer No ID of the Viber name from which the message will be sent if forwarding_message=1 and the SMS message is not delivered

Responses

200 — Completed successfully

{
    "sms_id": 2197871,
    "status": "NEW",
    "parts": 1
}

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

POST Sending Telegram Verification Code /api/v1/sendOtpTelegram
Request URL
POST https://app.sms.by/api/v1/sendOtpTelegram

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message query string Yes Only numbers, maximum 16 characters
phone query string Yes Phone number

Responses

200 — Completed successfully

{
    "sms_id": 2197871,
    "status": "NEW",
    "parts": 1
}

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

POST Sending WhatsApp Verification Code /api/v1/sendOtpWhatsApp
Request URL
POST https://app.sms.by/api/v1/sendOtpWhatsApp

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message query string Yes Only numbers, maximum 16 characters
phone query string Yes Phone number

Responses

200 — Completed successfully

{
    "sms_id": 2197871,
    "status": "NEW",
    "parts": 1
}

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

GET Creating a message for bulk sending /api/v1/createSmsMessage
Request URL
GET https://app.sms.by/api/v1/createSmsMessage

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
name query string No Newsletter name
message query string Yes Your message
alphaname_id query integer No Your alpha name ID
time query string No Date and time of sending (Date format '2019-05-24 10:22')

Responses

200 — Completed successfully

{
    "status": "ok",
    "parts": 1,
    "len": 31,
    "message_id": 2604834,
    "alphaname": "system",
    "time": 0
}

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

GET Checking the message status (status of the SMS mailing as a whole) /api/v1/checkSMSMessageStatus
Request URL
GET https://app.sms.by/api/v1/checkSMSMessageStatus

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message_id query string Yes Message ID obtained from the createSmsMessage method

Responses

200 — Completed successfully

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

GET Sending a message /api/v1/sendSMS
Request URL
GET https://app.sms.by/api/v1/sendSMS

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message_id query integer Yes Message ID from the createSmsMessage method
phone query string Yes Phone number

Responses

200 — Completed successfully

{
    "sms_id": 2204968,
    "status": "NEW"
}

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

GET Check SMS message status /api/v1/checkSMS
Request URL
GET https://app.sms.by/api/v1/checkSMS

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
sms_id query integer Yes SMS ID received with sendSMS

Responses

200 — Completed successfully

{
    "sms_id": 2637396,
    "sent": 1616407661,
    "delivered": 1616407673
}

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

GET Get a list of your messages /api/v1/getMessagesList
Request URL
GET https://app.sms.by/api/v1/getMessagesList

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
limit_offset query integer No Sample offset
limit_rows query integer No Sample limit (required if limit_offset is used)

Responses

200 — Completed successfully

{
    "result": [
        {
            "message_id": 2564327,
            "message": "68755",
            "parts": 1,
            "d_create": "2021-03-22 11:32:32",
            "status": "moderated"
        },
        {
            "message_id": 2564580,
            "message": "37271",
            "parts": 1,
            "d_create": "2021-03-22 11:32:32",
            "status": "moderated"
        }
    ]
}

400 — Incorrect request

429 — Request limit exceeded

500 — Server is not available

GET Getting a mailing list by message ID /api/v1/getSmsDeliveryList
Request URL
GET https://app.sms.by/api/v1/getSmsDeliveryList

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message_id query integer Yes Message ID
limit_offset query integer No Sample offset
limit_rows query integer No Sample limit (required if limit_offset is used)

Responses

200 — Completed successfully

{
    "result": [
        {
            "phone": 375293332211,
            "status": "delivered",
            "d_sent": "2021-03-22 11:32:32"
        },
        {
            "phone": 375293332212,
            "status": "sent",
            "d_sent": "2021-03-22 11:32:32"
        }
    ]
}

400 — Incorrect request

429 — Request limit exceeded

500 — Server is not available

POST Sending messages to the selected list /api/v1/sendSmsList
Request URL
POST https://app.sms.by/api/v1/sendSmsList

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
name formData string Yes Newsletter name
message formData string Yes Message text
d_schedule formData string Yes Estimated sending time in YYYY-MM-DD HH:MM format
list_id formData integer Yes ID of the list with contacts from the method (getSubscriberLists)
alphaname_id formData integer Yes Alpha name ID (getAlphanameId)

Responses

200 — Completed successfully

400 — Incorrect request

404 — Page not found

429 — Request limit exceeded

500 — Server is not available

POST Confirmation / receipt of information about the mailing /api/v1/confirmSendMessageByList
Request URL
POST https://app.sms.by/api/v1/confirmSendMessageByList

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
message_id formData integer Yes Mailing list ID received in the sendSmsList method
confirm formData integer Yes 0 - get information about the mailing, 1 - confirm the mailing

Responses

200 — Completed successfully

400 — Insufficient funds to continue

500 — Server is not available

GET Get all WEB and API mailings /api/v1/getSMSMessages
Request URL
GET https://app.sms.by/api/v1/getSMSMessages

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
type query string No Specify the message type WEB or API (To get all parameters, do not pass the field)

Responses

200 — Completed successfully

{
    "status": "success",
    "data": [
        {
            "id": 1173020,
            "name": "Notification",
            "d_create": 1614154034,
            "d_schedule": 1645612020,
            "type": "API",
            "parts": "27631",
            "count_phones": 27631,
            "status": "NEW",
            "sms_delivered": "0",
            "cost": "718.40600",
            "alphaname": "SMS.by"
        }
    ]
}

406 — Content not found

404 — Page not found

429 — Request limit exceeded

500 — Server is not available