Skip to main content

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​

Body

Details of the SMS message to be sent.

    tostring[]required

    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

    fromstring

    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

    senderIdstring

    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.

    subjectstring

    An optional subject for internal reference within your HelloSMS account. If not provided, it defaults to "API".

    Possible values: <= 200 characters

    messagestringrequired

    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

    delayinteger

    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.

    shortLinksboolean

    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.

    shortLinksDomainstring

    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]

    sendApiCallbackboolean

    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.

    callbackUrlstring<uri>

    The https URL that delivery status callbacks for this message are sent to. See Delivery callbacks for the format.

    Possible values: <= 2048 characters

    callbackRefstring

    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

    priorityClassstring

    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]

    Default value: transactional
    checkForBlockOverrideboolean

    Check the numbers against the HelloSMS block list, and don't send to the blocked ones.

    Default value: false
    useCountryNumberboolean

    Whether 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.

    Default value: true
    testModeboolean

    Run the request without sending anything or using credits. The response looks like a real send.

Responses​

The SMS was sent successfully.