SMS - Send with the API

This page details the SMS sending request (POST /sms), with full JSON examples and the list of possible response codes and error payloads.

For authentication, the base URL and the general request format, see SMS - Get started.

A successful request does not guarantee delivery of the SMS. The request is accepted synchronously, but the SMS is delivered asynchronously to the recipient's device. Use the SMS status request to check its delivery afterwards.

Request

POST /sms
Content-Type: application/json
Authorization: Basic <your credentials, base64-encoded>

Request body

Field	Type	Required	Description
phoneNumber	string	Yes	Recipient's phone number: either a French local number (10 digits), or an international number formatted as +<country-code><number>.
message	string	Yes	Message content, 600 characters maximum. One SMS is charged every 160 characters.
allowUnicode	boolean	No	Defaults to true. If false, forces GSM 03.38 encoding instead of unicode.
metadata	object	No	Free-form JSON object to tag the message with custom data (see example below).

Simple example

{
  "phoneNumber": "[phone]",
  "message": "Please call me back"
}

Example with custom metadata

The added metadata tag is returned when retrieving the SMS details.

{
  "phoneNumber": "[phone]",
  "message": "Please call me back",
  "metadata": {
    "myCustomerId": "123de32",
    "caller": "MyApp 2.2"
  }
}

Successful response

An accepted request returns 200 with the message identifier, to be used later on to check its delivery status.

{
  "messageId": "77a76363bd882992893",
  "smsCount": 1
}

Response codes and possible errors

The error body shape depends on which check rejected the request - there is no single unified format across status codes.

Code	Meaning
200	SMS accepted for sending.
400	Invalid request (missing/too-long field, unparsable phone number, or provider rejection).
422	Recipient not allowed for this account (see below).
429	Rate threshold (SMS/minute or SMS/hour) reached for this account.
503	No SMS provider currently available - retry later.

400 Bad Request

Three different situations return 400, with three different body shapes:

• A missing/blank field, or a message over 600 characters, is caught by field validation. The body is a flat map, one entry per invalid field:

  {
    "message": "length must be between 1 and 600"
  }

• A phoneNumber that cannot be parsed as a valid number at all (wrong format, unknown country code, non-numeric characters...) fails a later check, once past field validation. The body only has an error key, whose value is the phoneNumber you sent, verbatim:

  {
    "error": "+33 6 not-a-number"
  }

• If your account's SMS provider configuration itself rejects the request (for example an invalid fromName), the body is an array of causes instead:

  [
    {
      "code": "INVALID_MESSAGE_LENGTH",
      "on": "message",
      "message": "Message length cannot exceed 600 characters"
    }
  ]

422 Unprocessable Entity

The recipient is not allowed for your account. This covers three independent per-account policies: a destination-country whitelist, a destination-country blacklist, and a phone-number whitelist. All three produce the same body - the response does not say which one fired. This is 422, not 403: your credentials and role are fine, it's specifically this request's recipient that your account's policy rejects.

{
  "error": "RECIPIENT_NOT_ALLOWED"
}

No SMS is sent and no delivery is attempted when this happens.

If a country whitelist has at least one entry, it always takes precedence over the country blacklist, which is then ignored for that account.

429 Too Many Requests

Returned when your account's per-minute or per-hour SMS rate threshold is reached. The body shape matches the provider-rejection case above (an array of causes) - note that message is a generic, non-interpolated template here (the literal %s is not a typo), the actual detail (which threshold, how many SMS) is in args instead:

[
  {
    "code": "LIMIT_REACHED",
    "message": "Request cannot be completed because of limit [%s]",
    "args": ["Threshold of 10 SMS within a minute has been reached."]
  }
]

503 Service Unavailable

No SMS provider is currently available to send your message - retry later, following the pattern described below.

{
  "error": "No providers are currently available to send SMS, retry later"
}

Recommended client pattern

Vortext can have up to 5 seconds of downtime in case one of our clustered infrastructure nodes fails. In this case you will get a 502 or 503 error. To ensure message delivery, consider calling the service with this pattern:

sendSms();
if (failure) {
  wait(5 seconds);
  sendSms();
  if (failure) {
    thisIsARealFailure();
  }
}