Test cases for transactional SMS in the Sandbox: wrong numbers, long texts, no credits, repeats

The short answer: with a sandbox_ key, the API checks every request and answers as it would in Production, but no SMS goes out and nothing is charged: the status comes back simulated and the answer carries the X-API-Simulated: true header. It is the right place to prove, one by one, the cases your system will meet every day, including the wrong ones.

The cases to test

Case	What to send	What should come back
Normal send	A valid number and a short text	201, status simulated, with parts and encoding
Wrong number	For example 12	422, invalid_number
No text	An empty text field	422, text_required
Text too long	More than 1,600 characters	422, text_too_long
Text with accents	The same notice with «ã» or «ç»	More parts and a different encoding: check the cost
Sender not approved	A sender that has not been approved	422, sender_not_approved
Identical retry	The same request with the same Idempotency-Key	The same answer, with Idempotent-Replayed: true
Same key, different text	The same Idempotency-Key with another body	409, idempotency_conflict
Scheduled in the past	send_at set to a date that has passed	422, send_at_in_past
Key without permission	A key without sms:write	403, insufficient_scope

Each case should trigger the right reaction in your system: store the id, do not retry a 422, alert the team. If it reacts badly in the Sandbox, it will react badly in Production.

Keeping tests out of Production

1	Send the X-API-Mode: sandbox header in your tests. If the key is not a Sandbox key, the API refuses with mode_mismatch instead of sending.

2	Check the key's mode with GET /v1/token: the mode field says sandbox or production.

3	Keep the two keys in separate places (test settings and production settings), never in the code.

What the Sandbox cannot show you: how the message looks on the phone. Before opening up to customers, make one real Production send to your own number and check the sender, the parts and the text. And remember: a sandbox_ key reads real account data, such as the balance, so guard it just as carefully.

Going to Production

Create a prod_ key with the minimum permissions in the API Center in My MozOut and swap it into your settings: the request is identical, only the prefix changes. If GET /v1/token shows writes_simulated as true, the API is still in preparation and sends remain simulated. Keep a close eye on the history and the statistics in the first few days.

Want to start testing today without spending credits? See Transactional SMS.

See Transactional SMS

Categories

Categories