Skip to content
SMSRay
Print / PDF Download PDFFull reference PDF

Coverage

Ask the API where you can send instead of hard-coding countries. Nepal is live today; more countries are on the way.

GET/sms/coverage
https://api.smsray.com/api/sms/v1/sms/coverage

Where this API key can send today: your workspace's country, the destinations allowed for it, and the countries SMSRay delivers to now or soon.

Request

Headers

Retrieve coverage request headers
NameTypeRequiredRules
x-api-keystringrequiredYour secret key, ls_live_ followed by 48 hex characters.

Example request

curl https://api.smsray.com/api/sms/v1/sms/coverage \
  -H "x-api-key: $SMSRAY_API_KEY"

Response

200

200 application/json
{
  "country": "NP",
  "allowed": ["NP"],
  "live": [{ "code": "NP", "name": "Nepal" }],
  "comingSoon": [
    { "code": "BD", "name": "Bangladesh" },
    { "code": "IN", "name": "India" }
  ]
}

Response fields

Retrieve coverage response fields
NameTypeRequiredRules
countrystringrequiredYour workspace's country (ISO 3166-1 alpha-2). National-format numbers are read as numbers of this country.
allowedstring[]requiredCountries this key can send to right now. A number elsewhere returns 422 destination_not_supported.
liveobject[]required{ code, name } for every country SMSRay delivers to today.
comingSoonobject[]required{ code, name } for countries we are preparing. Not sendable yet.

Errors

Every error uses the same shape: { "error", "code", "details"? }. Branch on code, not on the message.

Retrieve coverage errors
HTTPcodeWhen
401unauthorizedThe x-api-key header is missing ("Missing x-api-key") or the key is unknown ("Invalid API key").
403client_disabledThe API client that owns this key has been disabled in the dashboard.
429rate_limitedYou exceeded your per-client request rate (default 20 requests per second). Honour Retry-After.
500server_errorSomething went wrong on our side. The body never contains a stack trace.

Notes

  • Use allowed to validate phone numbers in your sign-up form before you send, and to pre-select the country picker with country.
  • A public, unauthenticated variant without the workspace fields is available at GET https://api.smsray.com/api/sms/coverage. It returns { live, comingSoon } and is cached for 5 minutes.
  • Today Nepal is live; India and Bangladesh are coming soon. The response is always the current list, so don't hard-code it.