Send SMS
POST/api/v1/sms/send
This endpoint allows users to send SMS messages to one or multiple recipients. Messages can include optional parameters such as delayed delivery, shortened links, a per-message callback URL, a priority class, and test mode. Each request supports up to 1500 recipients.
Request
- application/json
- Body
- SMS sending example
- Delayed SMS sending example
- Example of sending SMS with short links
- Example of sending SMS with a callback URL and priority class
- Example of sending SMS from a sender by senderId
- Example of sending SMS from one of your numbers
- Example of keeping your own number for a recipient abroad
Body
Details of the SMS message to be sent.
The recipients: an array of phone numbers, or a single number as a string. Use the international format, for example +46701740610. A number without a country code is assumed to be in your account's country.
Possible values: <= 1500
A custom sender text to show instead of your default phone number. To send as one of your registered senders or numbers, use senderId instead. Leave out both to send from your main number, or from your number in the recipient's country if you have one (unless useCountryNumber is false, which always uses your main number).
Possible values: >= 3 characters and <= 11 characters
One of your senders or numbers, by its id from List senders: SND… for a registered sender (for example SND3F9A0C21) or NUM… for one of your numbers (for example NUM5E0C8A17). A number id sends from that number, and recipients can reply to it. If you have your own number in a recipient's country, a message sent with a number id to that recipient goes out from your number in that country instead, unless useCountryNumber is false, which sends it from the number you chose. Unlike a free-text from, the id is directly connected to the same sender as set up on the web. Use either from or senderId, not both.
An optional subject for internal reference within your HelloSMS account. If not provided, it defaults to "API".
Possible values: <= 200 characters
The text of the SMS. A message can be at most 20 SMS long: 3060 characters with the standard alphabet, or 1340 if it contains Unicode characters. We recommend at most 10. To see how many SMS it will be split into, read this article or send it with testMode.
Possible values: <= 3060 characters
Send the SMS later. Give the send time as a UNIX timestamp, for example 1678886400. A time in the past sends immediately. Until then you can cancel it with Cancel scheduled SMS.
Enable link shortening for the SMS message. When set to true, any URLs (starting with http:// or https://) in your message will be automatically shortened using the HelloSMS link shortening service. This can help reduce message length and save on costs.
When using the link shortening feature, you can select which domain you prefer for the shortened links. HelloSMS offers two options: ff.nu (currently the default) and out.io (note: up until 2025-05-09, out.io was the default).
Possible values: [ff.nu, out.io]
Send delivery status callbacks for this message, to callbackUrl or to your account's default callback URL. Off by default. Setting callbackUrl turns it on.
The https URL that delivery status callbacks for this message are sent to. See Delivery callbacks for the format.
Possible values: <= 2048 characters
Your own reference, for example an order id. It comes back in the delivery status callbacks, so you can match them to the message.
Possible values: <= 100 characters
How the message is queued. bulk is lower priority than the default, and priority is the highest. Priority sending has to be enabled for your account, contact support.
Possible values: [transactional, bulk, priority]
transactionalCheck the numbers against the HelloSMS block list, and don't send to the blocked ones.
falseWhether to send from your account's number for the recipient's country. By default, when a recipient is abroad and your account has a number for that country, the message goes out from that number, even when you chose another number. Set false to skip that: the message goes out from the number you chose, or from your main number when you chose none.
It has no effect when you send from a text sender (from, or a senderId that is a text sender), which is always used as it is. Any value other than true or false fails the request with Invalid value for useCountryNumber.
trueRun the request without sending anything or using credits. The response looks like a real send.
{
"to": [
"46701740610"
],
"from": "46701740609",
"subject": "API Test",
"message": "Testing API. Visit https://hellosms.se/#contact for more information. ",
"testMode": true
}
{
"to": [
"46701740610"
],
"from": "46701740609",
"subject": "API Test",
"message": "Testing API. Visit https://hellosms.se/#contact for more information. ",
"delay": 1742153738,
"testMode": true
}
{
"to": [
"46701740610"
],
"from": "46701740609",
"subject": "API Test",
"message": "Testing API. Visit https://hellosms.se/#contact for more information. ",
"shortLinks": true,
"testMode": true
}
{
"to": [
"46701740610"
],
"from": "46701740609",
"subject": "API Test",
"message": "Your order has shipped.",
"callbackUrl": "https://example.com/hellosms/callback",
"callbackRef": "order-1234",
"priorityClass": "bulk",
"testMode": true
}
{
"to": [
"46701740610"
],
"senderId": "SND3F9A0C21",
"subject": "API Test",
"message": "Testing API. Visit https://hellosms.se/#contact for more information. ",
"testMode": true
}
{
"to": [
"46701740610"
],
"senderId": "NUM5E0C8A17",
"subject": "API Test",
"message": "Testing API. Visit https://hellosms.se/#contact for more information. ",
"testMode": true
}
{
"to": [
"+4799999999"
],
"subject": "API Test",
"message": "Testing API. Visit https://hellosms.se/#contact for more information. ",
"useCountryNumber": false,
"testMode": true
}
Responses
- 200
- 400
- 401
The SMS was sent successfully.
Bad Request.
Unauthorized.