Send SMS with API v1.1

Send an SMS from a cloudnumbering number and track the message by its identifier.

Before you start

• Request an API access token.
• Use a from number assigned to the same organisation as the access token.
• Write to and from in E.164 format, including the leading +.
• Make sure your balance covers every SMS part.

The API v1.1 base URL is https://api.cloudnumbering.com/v1.1.

Send a message

1. Read your access token into an environment variable without putting it in shell history.

   Bash

   read -r -s -p 'Access token: ' CLOUDNUMBERING_ACCESS_TOKEN
   printf '\n'
   export CLOUDNUMBERING_ACCESS_TOKEN

2. Send POST /v1.1/sms.

   Shell

   curl --silent --show-error \
     --request POST \
     --header "Authorization: Bearer $CLOUDNUMBERING_ACCESS_TOKEN" \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+447700900001",
       "from": "+447700900000",
       "content": "Your appointment is tomorrow at 10:00."
     }' \
     'https://api.cloudnumbering.com/v1.1/sms'

3. Save result.sid from the response.

   JSON

   {
     "success": true,
     "result": {
       "sid": "00000000-0000-4000-8000-000000000001"
     }
   }

The SID identifies this message in delivery receipts and support investigations.

Request delivery receipts

Add dlrUrl to receive status updates at an HTTPS endpoint you control:

{
  "to": "+447700900001",
  "from": "+447700900000",
  "content": "Your appointment is tomorrow at 10:00.",
  "dlrUrl": "https://example.com/cloudnumbering/dlr"
}

Store the returned message SID so that you can match it to the sid in each delivery receipt.

Interpret the response

A successful API response means that the message was accepted for sending. It does not confirm delivery to the handset. Use a delivery receipt when your workflow needs the delivery outcome.

Warning: POST /v1.1/sms has no idempotency key. Do not automatically retry after a timeout, connection failure, or other unknown outcome. The original request might have succeeded, and a retry can send and charge for a second message.

Each SMS part is charged separately. cloudnumbering accepts no more than six parts in one outbound message. See SMS encoding and message length before sending long or Unicode content.

Troubleshooting

The API returns 400

Check that both numbers use E.164 format and that the content fits within six SMS parts. Content over the limit returns message too long.

The API returns 401

Request a new access token and check that the header starts with Authorization: Bearer .

The API returns 404

Confirm that from is a cloudnumbering number assigned to the organisation that issued the access token.

If the number belongs to the correct organisation, the destination might not have an outbound SMS rate. Record the X-Request-Id response header and follow Troubleshooting SMS. Repeating the same request will not resolve a missing rate.

The outcome is unknown

Do not submit the same message automatically. Record the UTC time and the X-Request-Id response header when available, then follow Troubleshooting SMS.

Next steps

• Send an SMS API reference
• Process SMS delivery receipts
• Understand SMS encoding and message length
• Review outbound SMS product guidance