Send an SMS

POST https://api.getaureusdesk.com/v1/sms/messages

Queues an SMS. 202 response. Its price in credits, that of the destination country (25 in Cameroon, see GET /sms/coverage), is reserved immediately: consumed if the SMS is sent, given back if it is rejected before sending.

Request body

Text: 160 characters, always in the SMS alphabet

Today, for all destinations, SMS are sent in the GSM alphabet, the one every phone displays. Your text is always converted to it, even when short:

€ [ ] { } ^ ~ | \ are accepted but count as 2. The response shows "normalized": true when the text was converted. A text emptied by the conversion (only emoji, for example) is rejected: 422 TEXT_INVALID.

Long message: 2 SMS (allowTwoParts)

Beyond 160 characters, the request is rejected (422 TEXT_TWO_PARTS_REQUIRED), never cut without your knowledge. With "allowTwoParts": true:

• the text (about 310 characters at most) is split between two words into 2 SMS of 159 characters at most, prefixed "1/2" and "2/2";
• it is billed per part: twice the country price (50 credits in Cameroon);
• the order is guaranteed: part 2 is only sent once part 1 has been delivered. If delivery of part 1 is not confirmed within 15 minutes, part 2 is cancelled and its credits given back (errorCode: PART1_NOT_DELIVERED);
• free credits cannot be used for 2-SMS messages;
• longer than 2 SMS: 422 TEXT_TWO_PARTS_MAX.

The response then gives smsCount: 2, totalCredits and parts, the list of both parts (part: "1/2" and "2/2", same groupId). id is the one of part 1. Cancelling a scheduled message cancels both of its parts.

Optional header: Idempotency-Key

Send the same key (100 visible characters at most) to replay a request without a new debit: the response returns the same message, with "replayed": true. If the same key is used for another number or another sender: 409 IDEMPOTENCY_CONFLICT. See Best practices.

Example

curl -X POST https://api.getaureusdesk.com/v1/sms/messages \
  -H "Authorization: Bearer adk_sms_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4821" \
  -d '{"to": "677000222", "text": "Order no 4821 confirmed. Delivery tomorrow.", "sensitive": false}'

const response = await fetch("https://api.getaureusdesk.com/v1/sms/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AUREUS_SMS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-4821",
  },
  body: JSON.stringify({ to: "677000222", text: "Order no 4821 confirmed." }),
});
const message = await response.json();

Response

{
  "id": "5b0f2c1e-8a4d-4f7e-9c3a-1d2b3c4d5e6f",
  "status": "QUEUED",
  "to": "+237*******22",
  "operator": "MTN",
  "countryIso": "CM",
  "priceCredits": 25,
  "senderId": "Aureus Desk",
  "errorCode": null,
  "groupId": null,
  "part": null,
  "scheduledAt": null,
  "createdAt": "2026-11-02T10:00:00.000Z",
  "sentAt": null,
  "deliveredAt": null,
  "likelyUndelivered": false,
  "normalized": false,
  "smsCount": 1,
  "totalCredits": 25
}

likelyUndelivered: true: the number belongs to a network we do not serve today (in Cameroon: Camtel, Nextel). The SMS is attempted; if it is rejected, the credits are given back.

Credits used

If you have free credits (promotional offer), they are used first, then your purchased credits (see Balance and top-ups).

Rejections before queuing (no debit)