REST API SMS Integration: Developer Quickstart Guide

You need to add SMS to your application. Maybe it is OTP codes for user verification. Maybe it is order confirmations for your e-commerce platform. Maybe your product team wants to add appointment reminders and they need it shipped by the next sprint.

‍

Whatever the use case, the integration itself should not take more than a morning. SMS APIs have been around for over a decade and the patterns are well-established. But choosing the right provider and understanding the nuances of deliverability, number types, and compliance can save you days of debugging and rework later.

‍

This quickstart covers the core concepts of REST API SMS integration, walks through code examples in Python, Node.js, and cURL, and highlights the practical decisions you need to make before your first message hits production.

Core Concepts Before You Write Code

Authentication

Every SMS API uses some form of credential-based authentication. The most common pattern is an API key and secret (or Account SID and Auth Token) passed in the request header or as HTTP Basic Auth credentials. Some providers use Bearer tokens.

‍

Store your credentials in environment variables, never in your source code. Use a secrets manager in production. Leaked API credentials mean someone else sends messages on your account and you pay the bill.

Message Segments

SMS messages are limited to 160 characters using GSM-7 encoding. Messages longer than 160 characters split into multiple segments, and you pay per segment. A 320-character message costs twice as much as a 160-character message.

‍

Unicode characters (emoji, non-Latin scripts, certain special characters) trigger UCS-2 encoding, which cuts your segment limit to 70 characters. A 150-character message with a single emoji becomes a 3-segment message. If cost matters, stick to GSM-7 characters and keep messages concise.

Number Types

Your "from" number determines throughput, cost, and carrier treatment. The three main types are 10DLC (local numbers requiring campaign registration), toll-free (nationwide, moderate throughput, requires verification), and short codes (highest throughput, highest cost, 8 to 12 week setup). For most applications, 10DLC is the default starting point.

Delivery Status and Webhooks

Sending a message is asynchronous. The API returns a message ID and a status of "queued" or "sent," but that does not mean the message reached the recipient. Carrier delivery reports come back later through webhooks, also called callbacks or status URLs.

‍

Set up a webhook endpoint that your SMS provider calls when a message status changes. Common statuses include queued, sent, delivered, failed, and undelivered. Log every status update. If your deliverability drops, those logs are the first place to look.

Sending Your First SMS: Code Examples

The following examples show the basic pattern for sending an SMS via REST API. The specific endpoint, authentication method, and payload format vary by provider, but the structure is consistent across the industry.

cURL

curl -X POST https://api.yourprovider.com/v1/messages \

  -u "$API_KEY:$API_SECRET" \

  -H "Content-Type: application/json" \

  -d '{"from": "+15551234567", "to": "+15559876543", "body": "Your order has shipped. Track: https://example.com/track/123"}'

Python (requests)

import requests

import os

response = requests.post(

'https://api.yourprovider.com/v1/messages',

auth=(os.environ['API_KEY'], os.environ['API_SECRET']),

json={

     'from': '+15551234567',

     'to': '+15559876543',

     'body': 'Your order has shipped.'

}

)

print(response.json())

Node.js (axios)

const axios = require('axios');

const response = await axios.post(

  'https://api.yourprovider.com/v1/messages',

  { from: '+15551234567', to: '+15559876543', body: 'Your order has shipped.' },

  { auth: { username: process.env.API_KEY, password: process.env.API_SECRET } }

);

console.log(response.data);

Handling Inbound Messages

Two-way messaging requires a webhook endpoint that receives inbound messages from your customers. When a customer replies to your message, the carrier routes their reply to your provider, which forwards it to your webhook URL.

‍

Your webhook receives a POST request containing the sender's phone number, the message body, and metadata like timestamp and message ID. Parse this payload to trigger the appropriate action in your application: confirm an appointment, process a keyword command, or route to a support queue.

‍

Make sure your webhook returns a 200 status code quickly. If your endpoint takes too long to respond, the provider may retry the delivery, resulting in duplicate processing. Acknowledge the webhook immediately and handle business logic asynchronously.

Error Handling and Retry Logic

SMS APIs fail. Carriers reject messages. Numbers are invalid. Rate limits get hit during burst sends. Your integration needs to handle these gracefully.

Invalid numbers

‍Validate phone numbers before sending. Use the provider's number lookup API if available, or at minimum validate E.164 format (+1XXXXXXXXXX for US numbers). Sending to invalid numbers wastes money and can hurt your sender reputation.

Rate limits

‍Most providers enforce per-second rate limits. If you are sending bulk messages, implement a queue with throttling rather than firing all requests simultaneously. Exponential backoff on 429 (Too Many Requests) responses prevents your application from hammering the API.

Carrier rejections

‍Messages can be rejected by carriers for content filtering, unregistered sender, or recipient opt-out. Log the error codes from failed deliveries and investigate patterns. If a high percentage of messages to a specific carrier are failing, the issue is likely your 10DLC registration or message content, not the API.

10DLC Registration: The Step Developers Often Skip

Your API integration works perfectly in the sandbox. You promote to production and messages start getting blocked. What happened?

‍

10DLC registration. Every business sending A2P SMS from local numbers in the US must register a Brand and Campaign through The Campaign Registry. Without registration, carriers filter, throttle, or block your messages. This is not a provider-specific requirement. It is carrier-mandated across AT&T, T-Mobile, and Verizon.

‍

Register your brand and campaign before going to production. Not after. The approval process takes 1 to 3 weeks, and delays in registration mean delays in your production launch.

‍

Signalmash handles 10DLC registration with hands-on support, reviewing your campaign details before submission to catch common rejection issues. Their team understands what carriers look for in campaign descriptions and sample messages, which means faster approvals and fewer back-and-forth cycles.

Choosing a Provider: What Developers Should Evaluate

Beyond the API documentation and pricing page, here is what actually matters in day-to-day development.

Sandbox quality

‍Can you send test messages without hitting production carriers? A good sandbox lets you test your integration end-to-end, including webhooks, without incurring charges or affecting your sender reputation.

Documentation accuracy

‍Try the code examples before committing. Copy-paste them and run them. If the documented examples do not work, that tells you about the quality of the rest of the platform.

Error messages

‍When something fails, does the API return a helpful error message or a generic 500? Good error messages save hours of debugging.

Support responsiveness

‍When you hit an edge case the documentation does not cover, how long does it take to get a useful answer from a human? Signalmash gives every customer a dedicated Slack channel with engineers who can answer API questions in real time. That is a material advantage over searching through community forums or waiting for a ticket response.

‍

The technical integration of an SMS API is the easy part. The ongoing operational work, managing deliverability, handling compliance, and debugging carrier issues, is where your provider relationship matters most. Choose a provider that makes the ongoing work easier, not just the initial integration.

‍