Sending SMS through the API: key, permissions, Sandbox and your first request

The short answer: the API is REST, speaks JSON and works over HTTPS only, at https://api.mozout.com/v1. Create a key on the API page in My MozOut with the sms:write permission, test in the Sandbox (nothing is sent or charged) and, once it works, switch to a Production key: the address and the operations stay the same.

The API in one minute

There is one API for your whole account, with 147 operations across 12 areas; SMS is one of them. Every request carries the key in the Authorization: Bearer <key> header. If APIs are new to you, start with what an API is, in plain words.

Creating the key

1	In My MozOut, open the API page and create a key. You can have up to 20 per account, for example one per application.

2	Pick permissions per area, with read and write kept apart. For SMS: sms:read to look things up (balance, messages, senders) and sms:write to send. Grant only what the application needs.

3	Pick an expiry: 30, 90 or 365 days, or none. You can add a spending limit and a list of allowed IPs.

4	Confirm with your password and the 6-digit code we send by e-mail. The key is shown only once: copy it straight away to a safe place on your server.

Has the key been exposed in a public repository, an e-mail or a web page? Follow what to do when an API key leaks, in the right order.

Sandbox and Production

	Sandbox	Production
Key starts with	sandbox_	prod_
Address and operations	The same	The same
The SMS	Validated, but not sent	Sent
Credits	Not charged	Taken from your SMS balance
In the response	"status": "simulated" and X-API-Simulated: true	The message’s real status

Your first request

curl https://api.mozout.com/v1/sms/messages \
-H "Authorization: Bearer sandbox_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7d4f2b1e-9c3a-4e8f-b6d2-1a5c3e9f0b7d" \
-d '{"number": "+258841234567", "text": "Your order is ready."}'

If all is well, you get a 201 with these fields:

Field	What it tells you
id	The message ID, so you can look it up later
status	The message status (in the Sandbox, simulated)
parts	How many parts the message was split into
encoding	The character set used: the standard one, or Unicode if the text has characters outside it
credits	The credits used (1 per part)

The sender field is optional: without it, the SMS goes out from the free NETMSG sender; with it, use an approved name, as explained in what a Sender ID is. Numbers are written with or without the country code, because the system can tell the country from the first digit: 841234567 goes to Mozambique and 923456789 to Angola. So +258 84 123 4567 and 258841234567 are the same number as 841234567.

The SMS operations

Operation	What it is for
POST /v1/sms/messages	Send an SMS (number, text and, optionally, sender)
GET /v1/sms/messages/{id}	See one message and its status
GET /v1/sms/messages	List your messages
GET /v1/sms/balance	Credit balance, daily_limit and sent_today
GET /v1/sms/senders	Your senders: the free one first, then yours, with their status (approved, pending, in_review, rejected)
POST /v1/sms/senders	Request a sender
GET and POST /v1/sms/templates	List and create templates
GET /v1/sms/stats	Sending statistics
GET and POST /v1/sms/opt-outs	Your account’s list of numbers that must not receive SMS

Useful headers and parameters

Name	What it is for
Idempotency-Key	Repeat a request safely: the same key with the same body returns the same response; with a different body, you get a 409
X-RateLimit-Limit, X-RateLimit-Remaining	The limit of 300 requests per minute per account, and how many are left
Accept-Language	API messages in Portuguese or English
X-Correlation-ID	Sent with every response; quote it when you ask support for help
page, per_page	Paging through lists, up to 100 per page

Next steps: what to do about each error is in SMS API errors and message statuses; to send sign-in codes, see verification codes by SMS.

Ready to connect your system to SMS? See the API page and create your first Sandbox key.

See the API page

Categories

Categories