Skip to main content
Two endpoints, neither of which sends anything.

​
What is left

balance is money on the account this login bills to. sms_count is "ND" — not determined — whenever the platform cannot convert money into a message count, which is the normal case as soon as you have more than one price.
Do not poll this before every send. It is a database read, it tells you nothing about whether this message will be accepted, and it doubles your request volume. Poll it on a schedule for alerting, and let a 402 be your per-message signal.

​
What a message will cost

The cost is unit_rate × submit_sm_count. submit_sm_count is the segment count, so this is also how you find out that a message you thought was one is actually three. /secure/rate sends nothing, charges nothing, and counts against no rate limit. That makes it safe to call on user-generated content before committing to a send — the one pre-flight check that is genuinely free.
Pricing can differ by country and network, which is why to is required rather than optional. A quote without a destination would be a guess.

​
The block behaviour, which explains an occasional refusal

Credit is reserved in blocks, not per message — around twenty messages’ worth at a time — which is what keeps the send path off the database.
You can see a 402 with money still on the account. Refills are asynchronous, so a message arriving while the next reservation is being taken is refused. Retrying succeeds, and this is the one 402 worth a retry.A persistent 402 with a healthy balance is a different matter — raise it with your provider.
The block size does not strand your credit. A reservation falls back through the full block, then the floor, then the single message that asked — so an account spends every unit it holds, and a small top-up works exactly as you would expect.

​
Product changes the price

product on either endpoint prices against a different product — from an allow list your provider maintains per login, and most logins are allowed none. The same allow list governs both endpoints, deliberately: a quote and a send cannot disagree about what you are permitted to name.

Statements and limits

Your usage history, and the ceilings that apply to you.

Price a message

Every field on /secure/rate.