Connecting an ERP, CRM or in-house system to SMS notices: what your developer needs

The short answer: any system that can make an HTTPS request can send SMS through our API: an ERP, a CRM, invoicing software or something built in-house. Your developer needs a key, the address and a handful of rules. This is the list to hand over.

What to give your developer

What	Detail
API address	https://{V:api_host}/v1, HTTPS only, JSON in and out.
Key	Created on the API page in My MozOut, sent in the Authorization: Bearer ... header. The key is shown only once.
Permissions	sms:write to send and sms:read to check statuses and the balance. Nothing else.
Sandbox and Production	A sandbox_ key for development (nothing is sent or charged) and a prod_ key for go-live.
Numbers	Mobile phones in Mozambique and Angola, 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.
Sender	Without the sender field, NETMSG is used. For your own name, an approved Sender ID.

The rules that prevent trouble

1	Idempotency-Key on every send, with a value tied to the event (invoice, order, booking). A retry never sends twice.

2	Batch for lists. For the day's notices, one request to /v1/sms/messages/batch instead of hundreds.

3	Limits. The account has a per-minute request limit, across all keys, and a daily sending limit. Read the X-RateLimit-Remaining header and, on a 429, wait for Retry-After.

4	Statuses by webhook, rather than asking every minute: the SMS webhook.

5	Numbers that opted out. A number on the account's list is refused with number_opted_out; your system should flag that customer and stop sending.

Keeping the key safe

The key stays on the server, in an environment variable or a file outside the public folder, never in a mobile app or browser code. When you create it you can give it a validity (30, 90 or 365 days, or none) and an IP list. If it leaks: what to do, in the right order.

When you ask support for help, send the X-Correlation-ID from the response, the time and the operation. Never send the key: support does not need it.

Start with a single notice, such as payment received, and get it working end to end in the Sandbox. The rest follow the same pattern. The first request is covered in sending SMS through the API.

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

See the API page

Categories

Categories