Delivery and test numbers
How SMS move from queued to delivered or failed, Twilio's official test numbers, and the status callbacks your app receives.
Try it in the demo.
What it solves
- Your app's status callback handler (sent, delivered, undelivered, failed) is never called during development.
- You need a number that always fails with a specific Twilio error, so a test can check your error handling every run.
- You want to see your app's "sending..." state, which instant delivery skips.
How a message moves
Outbound messages move through queued, sent and delivered, or end undelivered or failed with an error code. Each change:
- is added to the message's status history (in Message details);
- calls the message's status callback (
StatusCallbackon Twilio, orstatus_callbackon the native API) in the provider's format, with every attempt listed in Message details. A callback that fails with a5xx, a timeout or a connection error is sent again with the same request and signature: 5 attempts in total, after 1 s, 5 s, 30 s, 2 min and 10 min. A4xxis not retried; - fires
sms.statusfor your rules.
How fast, and whether it fails, is set in Settings > SMS:
| Profile | Does |
|---|---|
| Instant (default) | delivered at once |
| Realistic | queued, sent after about 300 ms, delivered after 1 to 3 s |
| Manual | stays sent until you press Set status in Message details |
A failure rate (0 to 100%) marks a random share of messages undelivered or failed.
Twilio's test numbers
SendMock's magic numbers are Twilio's official test numbers, with the same error codes, returned at once as an HTTP 400 with Twilio's error JSON. Tests written against SendMock match Twilio's own test mode.
Every number with its result and error code is in Magic numbers and addresses, generated from SendMock's code. For example, +15005550001 as the To is refused with Twilio's error 21211 (invalid number), and +15005550006 as the From passes.
Any other From is accepted. Turn on Strict Twilio test mode to reject them with 21606, as real test credentials do.
SendMock's after-send numbers
Twilio's test mode never sends status callbacks, so SendMock adds numbers that are accepted and then change status. For example, +15005550103 is accepted and then undelivered with 30007 (filtered by the carrier), and +15005550105 is delivered after 30 s. The full list has every one.
Vonage sends map the same outcomes to Vonage's own codes and status names. Turn all magic numbers off with Magic numbers in Settings; they then behave like any number.
Your own numbers
Rules such as "my QA number always fails with 30007" or "every +1555777* number is delivered after 10 s" are Advanced: SMS outcome numbers. Order: your rules first, then the magic numbers, then the profile and failure rate. Test a number in Settings shows which one applies.
Step by step: Recipe: failed SMS.
From the CLI, API and AI
| Do this | CLI | API | MCP tool |
|---|---|---|---|
| set a status by hand | sendmock sms status <smsId> <status> | POST /api/v1/sms/{smsId}/status | sendmock_sms_set_status |
| profile and failure rate | sendmock settings set | PATCH /api/v1/settings | sendmock_settings_update |
| list own outcome numbers | sendmock outcome-rule sms list | GET /api/v1/outcome-rules/sms | sendmock_outcome_rule_list |
| add one | sendmock outcome-rule sms create | POST /api/v1/outcome-rules/sms | sendmock_outcome_rule_create |
| test a number | sendmock outcome-rule sms test <number> | POST /api/v1/outcome-rules/sms/test | sendmock_outcome_rule_test |