Numbers & countries
Send numbers in E.164 and let the API tell you where you can deliver.
Number formats
E.164 is recommended: a +, the country code and the subscriber number, with no spaces, for example +9779801234567. The national format of your workspace's country is accepted too, and the country code without + works as well.
| You send | Read as | Notes |
|---|---|---|
+9779801234567 | +9779801234567 | E.164 — recommended. |
9779801234567 | +9779801234567 | Country code without +. |
9801234567 | +9779801234567 | National format of the workspace's country. |
014XXXXXX (landline) | — | 400 invalid_number: can't receive SMS. |
Every number must match ^\+?\d{7,15}$. SMSRay stores recipients in E.164, so to in message lookups and webhooks is always +<country code><number>.
Where you can send
Your workspace has a country, set when it is created. You can send to that country once SMSRay delivers there. Today Nepal is live; India and Bangladesh are coming soon. Ask the API for the current list with GET /sms/coverage instead of hard-coding it.
Number errors
| HTTP | code | When |
|---|---|---|
| 400 | invalid_request | to is missing, shorter than 7 digits or not digits (zod details). |
| 400 | invalid_number | The number can't receive SMS — for example a landline, or a number that fails its country's mobile rules. |
| 422 | destination_not_supported | The number is valid, but in a country your workspace can't send to yet. details is { country, allowed }. |
Show 422 differently from 400. The number isn't wrong — we just don't deliver there yet:
{
"error": "We don't deliver to India yet. This workspace can send to: Nepal.",
"code": "destination_not_supported",
"details": { "country": "IN", "allowed": ["NP"] }
}const res = await fetch("https://api.smsray.com/api/sms/v1/sms/send", { method: "POST", headers, body });
if (res.status === 422) {
const { code, details } = await res.json();
if (code === "destination_not_supported") {
const name = new Intl.DisplayNames(["en"], { type: "region" }).of(details.country);
return showError(`We don't deliver to ${name} yet.`); // details.allowed lists where you can send
}
}