Skip to main content
Seven endpoints, all JSON, all returning the same envelope. Six sit under /secure/ and take HTTP Basic authentication; /ping takes none.
The last two ask; they do not grant. A sender ID or template written through them is stored awaiting your provider’s approval and is not usable until they approve it. They arrived in gateway 0.9.7; against anything older they answer 404.

​
The envelope

Every response is a JSON object with either data or message — never both, and never a bare value at the top level.
Success
Failure
So the branch in your client is res.ok, and the human-readable reason is always at message. There is no error code field: the HTTP status is the code, and the string is for a person reading a log.

​
Authenticating

Basic, with your HTTP login as the username:
An SMPP login cannot use this API, and the refusal does not say so in as many words — it is a 403 reading Authentication failure, the same answer a wrong password gets. If a login works over SMPP and returns 403 here, check its type before you check its password.
Credentials go in the header and nowhere else. username and password as body fields are not ignored — they are rejected as unknown arguments, which is how a payload copied from a different gateway usually announces itself.

​
Underscores and hyphens are the same field

Every _ is rewritten to - before the body is parsed. So dlr_url and dlr-url are one field, and you may write whichever your language prefers. Two consequences worth knowing before they bite:
{"dlr_url": "…", "dlr-url": "…"} is a duplicate of one field, and the API refuses rather than silently picking one. This is deliberate: quietly choosing would mean a receipt going somewhere the caller did not intend.
It keeps its underscore. custom-tlvs is an unknown argument and returns a 400, because the normaliser exempts this one name — see Custom TLVs.

​
This reference is the authoritative one

It describes what the gateway actually accepts, and its examples have been run against a live instance.
If you have been given an OpenAPI or Swagger document, check it against these pages before generating a client from it. An older specification circulated that is wrong in three places you meet on the first day:
  1. custom_tlvs is an object, not an array of pairs.
  2. validity_period is an integer of minutes, not a string.
  3. product is missing from it entirely.
A client generated from that spec fails on its first call.

Errors

Every status this API returns, and what provokes it.

Quickstart

First message in under five minutes.