Overview
A message that stays 'queued' — never reaching DELIVRD or UNDELIV — usually means it was accepted by the gateway but not yet delivered by the destination operator: commonly because it is scheduled for later, throttled to your TPS limit, waiting out a validity period against a handset that is off or out of coverage, or held on a congested route. Check schtime, your throughput cap, and the DLR — a message only leaves the queue when the operator returns a final receipt.
It's scheduled for later
If you set schtime (with gmt), the gateway deliberately holds the message until that moment, so it sits queued until the scheduled time arrives. Check the schtime/gmt you submitted — a wrong GMT offset or a future date is the simplest reason a batch 'isn't sending'. Omit schtime to send immediately; the REST API returns a ScheduleId when a send is scheduled.
- schtime (yyyyMMddhhmm) + gmt holds the message until that time.
- A wrong gmt offset can push the send hours out.
- Omit schtime to send now.
- A scheduled batch returns a ScheduleId, not immediate delivery.
It's throttled to your TPS limit
A large batch drains at your account's allowed throughput (messages per second), so later messages remain queued while earlier ones go out — this is normal draining, not a failure. If sustained volume matters, request a higher TPS. Very large sends are better submitted as a recipient file to the bulk endpoint /sms/sendbulk than as one huge request.
- Big batches drain at your TPS cap — later parts wait.
- This is expected pacing, not an error.
- Request higher throughput for sustained volume.
- Use /sms/sendbulk for very large lists.
The handset is unreachable within the validity period
If the recipient's phone is switched off or out of coverage, the operator's SMSC stores the message and retries until the handset reappears or the validity period expires. During that window the message is legitimately queued. When validity expires undelivered, the DLR turns to UNDELIV/expired — so a long-queued message often resolves itself once the handset comes back online.
- SMSC store-and-forward retries an unreachable handset.
- Message stays queued until delivery or validity expiry.
- On expiry, DLR becomes UNDELIV/expired.
- Often resolves when the phone returns to coverage.
Check credits, route, and the real status
If nothing moves at all, confirm balance — a submit can fail with HTTP18 (insufficient credits) — and that the sender ID and route are approved for the destination. Don't infer state from the absence of a webhook: pull each message's status directly (on the legacy HTTP API: /websmpp/websmsstatus with the response ID).
- No movement at all? Check credits — HTTP18 is insufficient balance.
- Confirm sender ID and route are approved for the country.
- Read the true state with a status pull (legacy HTTP API: /websmpp/websmsstatus).
- Don't assume from a missing webhook — pull the status.