How to Send SMS to a UK Mobile Number From Your Application

To send an SMS to a UK mobile number from your application, submit an HTTPS request to an SMS gateway containing the destination in international format, the message text and a sender identity that has been set up with the provider beforehand. The API call is the easy part. What catches UK senders is everything around it: which sender IDs the networks will carry, the number format our API actually expects, how many characters become how many parts, and where the answer about delivery actually arrives.

This is the working version of that, in the order you would do it.

The short version

1. Get the sender identity agreed first. An alphanumeric sender ID of up to 11 characters, or a virtual number if you need replies. Registration with us takes about a working day.
2. Format the destination as 447700900123 — international, dialling code included, trunk zero dropped, no plus sign.
3. Send a request to PUT /v2.0/sms/send with dstaddr, txt and your sender in srcaddr.
4. Take delivery results from receipts, POSTed to a URL you configure, not by polling.
5. Test with sim, which runs the whole path without sending anything.

Sender identity in the UK

An alphanumeric sender ID is what makes a message arrive showing a business name rather than a number. It can be up to 11 characters using letters, digits and spaces, and it works for traffic originating inside and outside the UK, which not every market allows.

The catch is that it has to exist before you send. UK networks keep reserved and restricted sender IDs, and some require an originator to be registered or allowlisted before they will carry it. If your ID collides with a reserved one, a network may quietly substitute a different sender or reject the message, and neither shows up unless you are reading receipts. We check your ID against those lists and register it where a network requires it, typically in one working day. What we need from you is the company name, website and country, your industry, a message example, your opt-out method and how it is set up, and the relationship between your company and the sender ID. The UK SMS rules page has the full list.

If you need replies — opt-outs, confirmations, support — a sender ID is not enough, because alphanumeric senders are one-way. Two-way traffic runs on a UK virtual number or a short code. Our two-way SMS page covers which to choose.

Formatting a UK number

A UK mobile number in international format looks like +447700900123. Three things follow from that, and all three are common causes of a failed first request:

• Drop the trunk zero. 07700 900123 becomes 447700900123. Keeping the zero gives you a number that does not exist.
• Do not send the plus sign. Our API takes E.164 digits without it: dstaddr=447700900123. Other providers differ, so check rather than assume when you move.
• Do not send 0044. It is legal in E.164 and some gateways accept it, but the digit string above is what every UK destination expects.

One more: Ofcom reserves 07700 900000 to 07700 900999 for drama, so a test message to a number in that range never reaches a real person. It is a safe destination for a smoke test, and a bad one if you are waiting for a reply.

Because UK numbers are portable, the prefix no longer reliably says which network a handset is on. That matters if you are tempted to route or report by prefix: treat range-based assumptions as approximate, and read the receipt for what actually happened.

The request

The endpoint takes PUT (or POST as an alias) and reads parameters from the query string or a form-encoded body. Authentication is a bearer token carrying the sms permission.

curl -X PUT "https://sms.world-text.com/v2.0/sms/send" \
  -H "Authorization: Bearer $WT_TOKEN" \
  --data-urlencode "dstaddr=447700900123" \
  --data-urlencode "txt=Your order 1234 is on its way." \
  --data-urlencode "srcaddr=ExampleShop" \
  --data-urlencode "clientref=order-1234" \
  --data-urlencode "multipart=3"

The response reports submission, not delivery:

{
  "status": "0",
  "message": [
    {
      "state": "0",
      "dstaddr": "447700900123",
      "msgid": "01-BDE08A3F91CCB0BE-2C3FD89C508A1438",
      "credits": "10.71"
    }
  ]
}

state here is the SMSC submission result, and 0 means accepted. Keep the msgid: it is the only thing that ties the message to the receipt that follows.

The same request from an application, using fetch:

const body = new URLSearchParams({
  dstaddr: "447700900123",
  txt: "Your order 1234 is on its way.",
  srcaddr: "ExampleShop",
  clientref: "order-1234",
});

const res = await fetch("https://sms.world-text.com/v2.0/sms/send", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.WT_TOKEN}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body,
});

const result = await res.json();
if (result.status !== "0") throw new Error(`Rejected: ${result.status}`);
for (const m of result.message) {
  console.log(m.msgid, m.state, m.credits);
}

Two details worth using rather than discovering. clientref is echoed in the delivery receipt, so it is the right place for your order or ticket id; it is capped at 32 characters. And callback lets you set a receipt URL per message when one destination needs different handling.

Where delivery actually arrives

Submission is not delivery. The outcome comes back as a delivery receipt POSTed to the URL configured on your account, or to the callback you supplied:

{
  "msgid": "01-BDE08A3F91CCB0BE-2C3FD89C508A1438",
  "state": "DELIVRD",
  "error": "0",
  "date": "2611061432",
  "clientref": "order-1234"
}

Final states are DELIVRD, EXPIRED, REJECTD and UNDELIV, with ACCEPTD along the way. Treat them as words rather than numbers and match on the strings — the API is explicit that clients should parse them rather than compare numerically.

Do not poll /sms/query for status. It is deprecated, it reports the gateway’s internal state rather than the network’s, and it is the first thing that breaks under load.

How long messages become several messages

Encoding decides how much of your text survives, and it is not 160 characters in every case:

Encoding	One part	Per part when concatenated	Notes
GSM 7-bit	160 characters	153 characters	Default. Nine characters cost two positions each
UCS-2 (Unicode)	70 characters	67 characters	Switched on by an emoji, or non-Latin script

We accept enc of GSM, LATIN1 or UCS2, and multipart sets the maximum number of parts, up to nine. Text beyond that limit is discarded without error — the message sends, the tail does not arrive, and nothing in the response says so. Set multipart deliberately rather than accepting the account default, which is one part unless configured otherwise, and measure the message before you send it rather than after.

Every part is billed. UK destinations are 10.71 credits per part, so a three-part message costs 32.13 credits, published on the coverage page. If that arithmetic matters for your product, decide the ceiling in code, not in a template that a copywriter can outgrow.

Throughput, testing and errors

Submit no more than about ten messages per second per account. There is no machine-readable rate-limit header, so if you are looping, pace the loop yourself rather than retrying hard on the first rejection.

For testing, add sim to any request and the operation runs without sending: presence of the parameter is enough, and sim=false still simulates. It is the fastest way to check authentication, parameter names and response parsing before you spend a credit.

Errors are HTTP status codes with a numeric status in the body: 1200 for a missing destination, 1201 for an unknown path, 1202 for a bad request, 401 for a bad token, and 403 for a valid token without the right permission, an account that is disabled or out of funds, or a destination outside the account’s permitted profile. The API reference lists every code with the exact conditions.

Before you go live

• Sender ID registered and confirmed, not assumed.
• A test to a real UK handset, not only to the drama range.
• multipart set explicitly, and a length check in your own code.
• Receipts consumed and matched on msgid, with clientref carrying your own id.
• A plan for the four final states, including what you do when a message is EXPIRED.

That last one is where most implementations are thinnest: it is easy to treat “sent” as “delivered” and discover the difference months later in a support queue.

Where to go next

The UK SMS API page covers the integration surface, the developer reference has every operation and error code, and the UK SMS rules page sets out what the networks require of a sender. If you are deciding how to size messages for cost, start with SMS length.