Skip to main content

Get an SMS

GET/messaging/v1/sms/{id}

Returns an SMS by its id, with its current status, cost, and the reason if it wasn't delivered.

Path parameters​

  • #iduuidRequired
    The SMS's id, from the response when you sent it, from a webhook, or from a WhatsApp message's smsFallback.
    Example: e2c38865-dc0a-4299-baef-c07a9bfa9c33

To follow a message as it changes, use a webhook. Don't poll this endpoint.

Example request​

curl "https://sandbox-api.ponitor.com/messaging/v1/sms/e2c38865-dc0a-4299-baef-c07a9bfa9c33" \
-H "apiKey: $PONITOR_API_KEY"

Responses​

OK. The message, with its current status. A message that wasn't delivered has a failureCode (an E11 code) and a failureReason.

{
"message": {
"id": "e2c38865-dc0a-4299-baef-c07a9bfa9c33",
"channel": "SMS",
"direction": "OUTBOUND",
"sender": "ACME",
"recipient": "+231770000000",
"text": "Your Acme order 42 is on its way.",
"status": "EXPIRED",
"cost": 0.05,
"failureReason": "Recipient unreachable: phone was off or out of coverage until the message expired",
"failureCode": "E11001",
"externalId": "order-42",
"conversationId": null,
"createdAt": "2026-10-05T09:30:00.112Z",
"updatedAt": "2026-10-06T09:30:04.870Z"
}
}

The message object​

Every field is always there.

FieldTypeMeaning
iduuidPonitor's ID for the message.
channelstringAlways SMS.
directionstringOUTBOUND for messages you send, INBOUND for replies to your Short Code.
senderstringYour Sender ID or Short Code, or the number a reply came from.
recipientstringThe phone number, in international format, or your Short Code for a reply.
textstringThe message.
statusstringQUEUED, SENT, DELIVERED, EXPIRED, UNDELIVERED, UNKNOWN or FAILED. See Delivery statuses.
costnumberWhat the message cost, in US dollars. Refunded if it ends as FAILED.
failureReasonstring or nullWhy the message wasn't delivered, in plain words. Set for EXPIRED, UNDELIVERED and FAILED.
failureCodestring or nullThe same reason as a code that never changes, such as E11001. Branch on it. See Why a message wasn't delivered.
externalIdstring or nullYour reference. null for a reply.
conversationIduuid or nullGroups the messages with one person, such as replies to your Short Code.
createdAtdate-timeWhen Ponitor accepted it.
updatedAtdate-timeWhen it last changed, usually its latest status.

Fields from before /sms aren't here: the message is in text, never content, and the reason is failureReason, not failedReason. An SMS has none of WhatsApp's fields. /messages and the webhooks still have content and failedReason.