Get an SMS
/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
- 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
- Node.js
- Python
- PHP
curl "https://sandbox-api.ponitor.com/messaging/v1/sms/e2c38865-dc0a-4299-baef-c07a9bfa9c33" \
-H "apiKey: $PONITOR_API_KEY"
const response = await fetch('https://sandbox-api.ponitor.com/messaging/v1/sms/e2c38865-dc0a-4299-baef-c07a9bfa9c33', {
headers: { apiKey: process.env.PONITOR_API_KEY },
});
console.log(response.status, await response.json());
import os
import requests
response = requests.get(
"https://sandbox-api.ponitor.com/messaging/v1/sms/e2c38865-dc0a-4299-baef-c07a9bfa9c33",
headers={"apiKey": os.environ["PONITOR_API_KEY"]},
timeout=30,
)
print(response.status_code, response.json())
<?php
$ch = curl_init('https://sandbox-api.ponitor.com/messaging/v1/sms/e2c38865-dc0a-4299-baef-c07a9bfa9c33');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['apiKey: ' . getenv('PONITOR_API_KEY')],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status, ' ', $body, PHP_EOL;
Responses
- 200
- 401
- 404
- 429
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"
}
}
Unauthorized. The API key is missing (E02001), wrong or revoked (E02002), or sent to the other base URL (E02003). See API keys and base URLs.
Not Found. Your team has no SMS with this id (E01005). A WhatsApp message's id answers the same: read it with Get a WhatsApp message.
{
"error": {
"type": "not_found_error",
"code": "E01005",
"name": "NotFound",
"message": "message with id (e2c38865-dc0a-4299-baef-c07a9bfa9c33) not found",
"doc_url": "https://docs.ponitor.com/api/errors#E01005",
"request_id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a"
}
}
Every error has this error object. The body also still carries fields from before codes, which are deprecated. See The error body.
Too Many Requests. Your team went over its rate limit (E01011). Wait, then try again.
The message object
Every field is always there.
| Field | Type | Meaning |
|---|---|---|
id | uuid | Ponitor's ID for the message. |
channel | string | Always SMS. |
direction | string | OUTBOUND for messages you send, INBOUND for replies to your Short Code. |
sender | string | Your Sender ID or Short Code, or the number a reply came from. |
recipient | string | The phone number, in international format, or your Short Code for a reply. |
text | string | The message. |
status | string | QUEUED, SENT, DELIVERED, EXPIRED, UNDELIVERED, UNKNOWN or FAILED. See Delivery statuses. |
cost | number | What the message cost, in US dollars. Refunded if it ends as FAILED. |
failureReason | string or null | Why the message wasn't delivered, in plain words. Set for EXPIRED, UNDELIVERED and FAILED. |
failureCode | string or null | The same reason as a code that never changes, such as E11001. Branch on it. See Why a message wasn't delivered. |
externalId | string or null | Your reference. null for a reply. |
conversationId | uuid or null | Groups the messages with one person, such as replies to your Short Code. |
createdAt | date-time | When Ponitor accepted it. |
updatedAt | date-time | When 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.