SMS segments and credits
One message can use two credits
Section titled “One message can use two credits”The API limits each text to two segments. One segment represents one credit per recipient: a two-segment message addressed to three recipients requires six credits.
A message’s segments field describes the count retained by the service. The displayed length in your interface is insufficient to reproduce that count.
Current counting rules
Section titled “Current counting rules”The service normalizes text to NFC for counting. For its GSM-compatible branch, it also treats some typographic punctuation as simple equivalents: for example, a curly apostrophe as a straight apostrophe, or … as three dots.
Characters in the main alphabet count as one unit; extension characters count as two. The service’s count includes €, ^, {, } and ê among its two-unit characters. One visible character therefore does not necessarily mean one unit.
Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.
| Calculation | One segment | Beyond one segment |
|---|---|---|
| Service GSM branch | Up to 160 units | 153 units per segment |
| Service Unicode branch | Up to 70 code points after NFC | 67 code points per segment |
If any character falls outside the recognized alphabet, the whole message uses the Unicode branch. The internal counter calls this branch UCS-2; its current calculation counts normalized code points and is not a universal UTF-16 unit counter.
The following examples use characters with outcomes determined by the current calculation:
Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.
| Text | Result | V2 admission |
|---|---|---|
A repeated 160 times | 1 segment | Accepted if other conditions are met |
A repeated 161 times | 2 segments | Accepted if other conditions are met |
A repeated 306 times | 2 segments | Accepted if other conditions are met |
A repeated 307 times | 3 segments | Rejected |
€ repeated 80 times | 1 segment | Accepted if other conditions are met |
€ repeated 81 times | 2 segments | Accepted if other conditions are met |
ā repeated 70 times | 1 segment | Accepted if other conditions are met |
ā repeated 71 or 134 times | 2 segments | Accepted if other conditions are met |
ā repeated 135 times | 3 segments | Rejected |
This normalization serves the calculation. Do not infer that the submitted text will be rewritten in the received message. For text mixing emoji, combining sequences and unusual symbols, do not apply a simple limit to the displayed character count.
Validation limits
Section titled “Validation limits”text must be a non-empty string and cannot contain only whitespace. The field also has a 320-character ceiling before segment counting. This does not allow 320 GSM letters: A repeated 307 times already exceeds two segments.
SMS v2 has no public endpoint for simulating cost. Creating a message can reserve or consume credits and send an SMS; do not use it as a calculator without side effects.
Reservation and consumption
Section titled “Reservation and consumption”A schedule or batch reserves the required credits at admission. For a batch, the initial amount is text segments × recipient count. The batch’s credits_reserved field preserves that initial amount.
Provider acceptance and handset delivery are distinct. Do not wait for delivered to consider that credits may have been consumed. An uncertain outcome can retain reserved credits; do not treat it as a refund.
Retrieve GET /api/sms/v2/balance/ with balance.read for total, available and reserved. Expired credits cannot fund a new submission. A favorable balance read does not prevent 409 insufficient_credits if other operations use the balance in the meantime.
See credits and contacts, batches and error handling.