Skip to main content

Send multiple SMS messages

POST 

/api/v1/sms/sendMulti

This endpoint allows you to send multiple, distinct SMS messages with a single API request. Each message within the messages array functions similarly to the /send endpoint, allowing individual message parameters. You can also define global parameters that apply to all messages, but note that message-specific parameters will override these global settings. The global parameters are sendApiCallback, callbackUrl, testMode, from, senderId, delay, shortLinks and useCountryNumber.

The batch-level from or senderId is used for every message that sets neither its own from nor its own senderId. A message that sets either one of them uses only that, and the batch-level sender is ignored for it. You can't set both a non-empty from and a senderId at batch level. Get sender ids from List senders; an id can be a registered sender or one of your numbers.

Important: A single request can include a maximum of 1500 recipients across all messages.

Each message is validated and sent on its own. If a message is rejected, for example because of a bad callbackUrl, only that message fails. The response is still 200 with status: success, and the failure is reported in that message's entry in messages and counted in totalFailed. A request that as a whole can't be processed returns 400.

Request​

Body

Batch of SMS messages to be sent in a single request.

    messages object[]required

    Each message in the array is treated as an independent message, with the same parameters and behavior as the /send endpoint.

  • Array [
  • 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.

  • ]
  • delayinteger

    Schedule the SMS message to be sent at a later time. Provide the desired send time as a UNIX timestamp (e.g., 1678886400). Until the scheduled time, you can cancel a scheduled message with its apiMessageId using 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. Short-link codes are not a fixed length. They can be longer than 4 characters, and they can grow over time. Don't assume a fixed length for shortened links, for example when you estimate message length or match links in sent messages. Use textLength and messageCount in the response for the actual values.

    sendApiCallbackboolean

    Enable SMS delivery status callbacks for this message. When set to true, HelloSMS will send a callback with updates on the delivery status of the message(s) to the callbackUrl, or to your account's default callback URL if none is set. This is disabled by default.

    callbackUrlstring<uri>

    A callback URL applied to every message in the batch that doesn't set its own callbackUrl. The same rules as for /send apply, and each message is checked on its own: an invalid URL fails each message that uses it, not the whole batch. Setting callbackUrl also turns on sendApiCallback for those messages.

    Possible values: <= 2048 characters

    testModeboolean

    This parameter allows you to test your SMS sending process without using any real credits or delivering messages to recipients. When enabled, the API will process your request as if it were sending a real message, but no messages will actually be sent.

    fromstring

    Set the sender ID for the SMS message. This allows you to use a custom alphanumeric string (up to 11 characters) instead of your default phone number.

    senderIdstring

    A registered sender (SND…) or one of your numbers (NUM…), identified by its id from List senders, used for every message in the batch that sets neither its own from nor its own senderId. A message that sets either one of them uses only that. A number id sends from that number; if you have your own number in a recipient's country, the message to that recipient goes out from your number in that country instead, unless useCountryNumber is false, which sends it from the number you chose.

    You can't set both a non-empty from and a senderId at batch level: the whole request is rejected with Cannot specify both from and senderId. A message whose senderId doesn't resolve fails on its own with Unknown or unavailable senderId, and the response is still 200.

    useCountryNumberboolean

    Applied to every message in the batch that doesn't set its own useCountryNumber; a message's own value wins. Set false to send from the number you chose, or from your main number when you chose none, even when a recipient is abroad and your account has a number for their country. It has no effect on a message sent from a text sender.

    A batch-level value other than true or false rejects the whole request with Invalid value for useCountryNumber. A bad value on a single message fails only that message, and the response is still 200.

    Default value: true

Responses​

The request was processed. The top-level status is success and the HTTP status is 200 even when some or all of the messages failed, so check totalFailed and the status of each message in messages.