SMS API Integration Guide: Sending Your First Message via REST

Sending an SMS from code is one of those tasks that looks trivial until you actually do it. The HTTP request itself takes minutes; the parts that take real thought are authentication, sender identity, character encoding, delivery tracking and what happens when a message fails. This guide walks through a typical REST-based SMS integration in the order you will actually encounter each step.

Before you write any code

Gather four things first. Skipping this stage is the most common reason a first integration stalls.

API credentials. Usually an API key or a username/password pair issued from your provider's web panel. With UIPAPP, credentials are available in the panel once your account is opened (account setup happens over WhatsApp or Telegram).
An approved sender ID (originator). In many countries, including Turkey, the alphanumeric sender name shown on the recipient's phone must be registered in advance. Start this approval early — it is often the longest lead time in the whole project.
Message templates, if you need them. Transactional and OTP traffic frequently requires pre-approved content patterns. UIPAPP supports a template system for OTP traffic alongside priority routing for that type of message.
Prepaid credit on the account. UIPAPP uses a per-SMS prepaid credit model rather than a subscription, so make sure the balance is loaded before you start testing.

Understanding the request

Almost every SMS REST API follows the same shape: an authenticated POST request with a JSON body describing who the message goes to, who it comes from, and what it says. Conceptually:

Endpoint — an HTTPS URL for sending messages. Always use HTTPS; never send credentials over plain HTTP.
Headers — Content-Type: application/json plus your authentication header, for example Authorization with an API key.
Body fields — typically a recipient list, a sender/originator value, the message text, and optional fields such as a client-side reference ID or a scheduled send time.

A minimal body usually looks something like {"from": "BRANDNAME", "to": ["+905xxxxxxxxx"], "text": "Your code is 123456"}. Field names differ between providers, so treat this as a shape rather than a copy-paste snippet and confirm the exact parameter names in your provider's API documentation.

Phone number formatting

Use E.164 format — country code with no spaces, dashes or parentheses. If your database stores national-format numbers, normalise them at the boundary of your application rather than inside the sending function. A small normalisation helper saves an enormous amount of debugging when you later expand to more countries; UIPAPP reaches 200+ destinations including Turkey, Cyprus and Europe, and each one has its own local habits for how users type their number.

Encoding and message length

Plain GSM-7 characters allow more text per message part than Unicode. The moment you include Turkish characters such as ş, ğ or ı — or emoji — the message may switch to Unicode encoding and split into more parts, each billed separately. Two practical rules: send the body as UTF-8 in your JSON, and preview how many parts a message will consume before you blast it to a large list.

Reading the response

A successful send response normally returns a message ID (or one per recipient) and an accepted status. Store that ID against your own record immediately. Without it you cannot correlate later delivery reports, and support requests become guesswork.

Treat accepted as distinct from delivered. The API confirming acceptance means the platform has queued the message, not that the handset received it. Final state arrives asynchronously.

Delivery reports and webhooks

There are two ways to learn a message's fate. Polling a status endpoint is simple but wasteful at volume. Webhooks are the better long-term choice: you expose an HTTPS endpoint, and the platform posts status updates to it as they arrive. UIPAPP provides instant delivery reports in the panel and webhook support for programmatic consumption.

When you build a webhook receiver, keep four habits:

Respond quickly with a 2xx and process the payload asynchronously.
Make handling idempotent — the same status may arrive more than once.
Validate the request before trusting it, and keep the URL non-guessable.
Log the raw payload during the first weeks of production; it is invaluable when a carrier returns an unusual status.

OTP-specific considerations

One-time passwords are latency sensitive and security sensitive. A few implementation notes that matter more than the API call itself:

Generate the code server-side, store only a hash, and set a short expiry.
Rate-limit per phone number and per IP to blunt abuse and pumping attempts.
Keep the message short and unambiguous, and avoid links inside OTP text.
Use a route intended for transactional traffic. UIPAPP offers priority routing for OTP alongside its template system, which helps keep verification messages out of a marketing queue.

Error handling and retries

Map provider errors into two buckets: permanent and transient. Invalid number, unapproved sender or insufficient credit are permanent — retrying will only burn attempts. Timeouts and 5xx responses are transient and deserve a retry with exponential backoff. Always send a client-side reference ID with each request so a retry after an ambiguous timeout can be deduplicated instead of double-sending.

Go-live checklist

Credentials stored in environment variables or a secret manager, never in the repository.
Sender ID approved for every country you target.
Numbers normalised to E.164 at input time.
Message IDs persisted and linked to your own records.
Webhook endpoint live, idempotent and monitored.
Alerts for low prepaid balance and for a sudden drop in delivery rate.
Opt-out handling in place for anything non-transactional.

Once the first message goes through, the remaining work is mostly operational: watching delivery rates, tightening error handling and keeping templates current. If you are building on UIPAPP, the panel and REST API cover both sides of that — the manual view for day-to-day checks and the API for everything your application does automatically.