SMS API: definition and how it works
Published and updated
An SMS API is a programmatic interface, almost always HTTP, that lets software send text messages, read the ones that arrive, and check what happened to each one.
How it works
A typical SMS API has three parts. A send call takes one or more recipients in international format plus a message body, and returns an identifier for the message or batch. A receive path gives you inbound messages, either by polling a messages endpoint or by having the provider POST each one to a webhook on your server. A status path tells you whether a message was accepted, sent, delivered or failed, again by polling or by webhook events.
Authentication is usually a static API key sent in a header. The key is scoped to an account, so the same code keeps working when you add or swap the hardware behind it. Good APIs make that explicit: you send to an account-level endpoint and the provider decides which connection or device carries the message.
Two details matter more than the rest of the surface. Recipient numbers must be in E.164 format, because a national number is ambiguous once it leaves the country. And a message longer than one segment is split and billed as several SMS, so an API that reports segment counts saves you from surprise costs.
SDKs wrap the same HTTP calls in a language's idiom. They are convenient but never required. Any language that can make an HTTPS request with a header can use an SMS API directly.
How this applies with textbee
The textbee API is REST over HTTPS with an x-api-key header. POST /gateway/send-sms sends to one or many recipients, GET /gateway/messages returns sent and received messages with cursor pagination, and webhooks push MESSAGE_RECEIVED, MESSAGE_SENT, MESSAGE_DELIVERED and MESSAGE_FAILED events. There is a JavaScript SDK, and every other language calls the endpoints directly.
Related terms
- SMS gateway: An SMS gateway is the piece of software or hardware that takes a message from an application and hands it to a mobile network so it arrives as a text on a phone.
- Webhook: A webhook is an HTTP request a service sends to a URL you own when something happens, so your code learns about an inbound SMS or a delivery event the moment it occurs instead of polling for it.
- E.164: E.164 is the ITU standard for international phone numbers: a plus sign, the country code, and the national number with no spaces or punctuation, at most fifteen digits.
- Delivery receipt: A delivery receipt is the network's report that an SMS reached the recipient's handset, or failed to, surfaced by a gateway as a status on the message.
Frequently asked questions
Do I need an SDK to use an SMS API?
No. An SDK is a wrapper around HTTP calls. If your language has an HTTP client you can send and receive SMS with a few lines and no dependency.