Running an outbound SMS campaign using the Agentless SMS API for appointment reminders. The campaign sends approximately 5,000 messages per day from a pool of 10 SMS-enabled phone numbers.
Starting Monday, messages are queuing successfully (the API returns 202 Accepted) but approximately 30% are never delivered. The message status stays in “Queued” state indefinitely - it never transitions to “Sent” or “Failed.”
The undelivered messages are not returning any error. They just sit in the queue. The delivered messages go through normally within 2-3 seconds.
Our API call:
POST /api/v2/conversations/messages/agentless
{
"fromAddress": "+1XXXXXXXXXX",
"toAddress": "+1YYYYYYYYYY",
"toAddressMessengerType": "sms",
"textBody": "Reminder: Your appointment is tomorrow at 2:00 PM."
}
We rotate through our 10 numbers in round-robin. The messages that fail are not correlated with any specific fromAddress - all 10 numbers have both successful and stuck messages.
Is there a throughput limit on the Agentless SMS API that we are hitting?
The Agentless SMS API has a throughput limit that is tied to your SMS number pool, not the API rate limit. Each SMS-enabled number in Genesys Cloud has a carrier-enforced sending rate of 1 message per second (1 MPS). With 10 numbers, your maximum throughput is 10 MPS.
5,000 messages per day averages out to approximately 0.06 MPS, which is well within your capacity. However, if your campaign sends messages in bursts rather than evenly distributed throughout the day, you can easily exceed the 10 MPS limit during burst windows.
When the MPS limit is exceeded, the Genesys Cloud SMS gateway queues the excess messages. But there is a queue depth limit of approximately 500 messages per number. Once the queue fills, additional messages are accepted by the API (202 response) but dropped by the gateway. They remain in “Queued” status because the gateway never processes them.
The fix is to implement client-side rate limiting. Space your API calls to no more than 8 messages per second (leaving 2 MPS headroom for retries):
import time
for message in campaign_messages:
send_sms(message)
time.sleep(0.125) # 8 MPS max
For the stuck messages, they will not auto-recover. You need to query for messages in “Queued” status older than 10 minutes and re-send them.
The MPS limit explanation is correct. From a compliance perspective, there are additional considerations for outbound SMS campaigns that are critical for financial services.
First, the 10DLC (10-Digit Long Code) registration requirements. If your 10 SMS numbers are standard local numbers (not short codes), they must be registered with The Campaign Registry (TCR) for A2P (Application-to-Person) messaging. Unregistered numbers have severely throttled throughput - often as low as 0.2 MPS per number instead of 1 MPS. This could explain why your effective throughput is lower than expected.
Check your number registration status in Admin > Telephony > SMS Number Management. Each number should show a “Campaign” status of “Registered” or “Verified.” If any show “Pending” or “Unregistered,” those numbers are being throttled by the carrier.
Second, ensure your message content includes an opt-out mechanism (“Reply STOP to unsubscribe”). Carriers will silently filter messages that do not include opt-out language, which would also appear as indefinitely queued messages on your end.