Delivery status
Acceptance and delivery are separate events
Section titled “Acceptance and delivery are separate events”A successful HTTP response confirms the result of the API operation. It does not prove that the recipient received the message.
Use the public identifier returned at creation to retrieve GET /api/sms/v2/messages/{id}/.
Scroll horizontally if needed. Keyboard: Tab, then the left and right arrow keys.
| Status | Meaning |
|---|---|
scheduled | The message is recorded for a future time. |
processing | Sending is being processed. |
accepted | The submission was accepted; delivery is not yet confirmed. |
delivered | A receipt confirms delivery. |
undeliverable | The delivery outcome indicates that delivery is impossible. |
blocked | Sending is blocked before submission to the provider. |
failed | Sending failed with a definite outcome. |
unknown | Available evidence is insufficient to determine the outcome. |
You will not necessarily observe every state while polling. Receipts can arrive quickly, late or more than once.
Poll responsibly
Section titled “Poll responsibly”The key needs delivery.read and must belong to the message’s organization.
Retain the last known state and gradually increase the interval between polls while no terminal result is available. Handle any HTTP 429 limit according to the response instructions.
For batches, retrieve aggregate counts and page through messages using the returned cursor. Successful batch creation does not replace individual delivery outcomes.
Make uncertainty visible
Section titled “Make uncertainty visible”Do not display unknown as “not sent”. Show an explicit state and retain the identifier for investigation.
A delay without a receipt is also insufficient to conclude that delivery failed.
If the outcome remains uncertain, contact support with the identifier and relevant time period.