Send an SMS
/messaging/v1/smsSends one SMS to one number. Ponitor returns the message, already charged and queued. Its status changes as the network reports back.
Request body
- Your approved Sender ID or Short Code.Example:
ACME - The phone number, in international format, with or without the +.Example:
+231770000000 - The handle of the workspace to send from and charge, such as
gbarnga-branch. Leave it out for Main. See Workspaces.Example:gbarnga-branch - Your own reference, up to 64 characters, unique within your team. If you reuse one on an SMS, you get the original back with
200. Nothing is sent or charged again. See Retries and externalId.Example:order-42 - The message, 2 to 640 characters. Required unless you send
template.Example:Your Acme order 42 is on its way. - A one-time code, instead of
text. Ponitor writes the message and sends it ahead of your other SMS. See One-time codes.Example:{ "id": "otp", "parameters": { "code": "482910", "duration": "10 minutes" } }2 child parameters
otp, the only template an SMS can be sent with.- The values Ponitor fills in.
Send text or template, not both. Fields not listed here are refused, and so is channel: this path only sends SMS. See Sending SMS for how SMS works.
Example request
- curl
- Node.js
- Python
- PHP
curl -X POST "https://sandbox-api.ponitor.com/messaging/v1/sms" \
-H "apiKey: $PONITOR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sender": "ACME",
"recipient": "+231770000000",
"externalId": "order-42",
"text": "Your Acme order 42 is on its way."
}'
const response = await fetch('https://sandbox-api.ponitor.com/messaging/v1/sms', {
method: 'POST',
headers: {
apiKey: process.env.PONITOR_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
sender: 'ACME',
recipient: '+231770000000',
externalId: 'order-42',
text: 'Your Acme order 42 is on its way.',
}),
});
console.log(response.status, await response.json());
import os
import requests
response = requests.post(
"https://sandbox-api.ponitor.com/messaging/v1/sms",
headers={"apiKey": os.environ["PONITOR_API_KEY"]},
json={
"sender": "ACME",
"recipient": "+231770000000",
"externalId": "order-42",
"text": "Your Acme order 42 is on its way.",
},
timeout=30,
)
print(response.status_code, response.json())
<?php
$ch = curl_init('https://sandbox-api.ponitor.com/messaging/v1/sms');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'apiKey: ' . getenv('PONITOR_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'sender' => 'ACME',
'recipient' => '+231770000000',
'externalId' => 'order-42',
'text' => 'Your Acme order 42 is on its way.',
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status, ' ', $body, PHP_EOL;
Responses
- 201
- 200
- 400
- 401
- 403
- 409
- 429
- 500
Created. The message was accepted, charged and queued. The body is the message.
{
"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": "QUEUED",
"cost": 0.05,
"failureReason": null,
"failureCode": null,
"externalId": "order-42",
"conversationId": null,
"createdAt": "2026-10-05T09:30:00.112Z",
"updatedAt": "2026-10-05T09:30:00.112Z"
}
}
OK. The externalId was already used on an SMS. The body is the original message in its current state, in the same shape as 201. Nothing new was sent or charged, even if the details differ.
Bad Request. A field is missing or invalid (E01001, with each field in details), the sender isn't yours (E10001), or the balance is too low (E03001).
{
"error": {
"type": "validation_error",
"code": "E01001",
"name": "ValidationError",
"message": "The request has 1 problem.",
"doc_url": "https://docs.ponitor.com/api/errors#E01001",
"request_id": "c1f0b7a2-5e1d-4c8e-9a0b-7d6e5f4c3b2a",
"param": "externalId",
"details": [
{ "param": "externalId", "message": "externalId is required" }
]
}
}
{
"error": {
"type": "billing_error",
"code": "E03001",
"name": "InsufficientBalance",
"message": "Insufficient account balance. Top up to continue sending.",
"doc_url": "https://docs.ponitor.com/api/errors#E03001",
"request_id": "2d017493-d307-4628-b9a3-068160069183"
}
}
Every error has this error object. The body also still carries fields from before codes, which are deprecated. See The error body.
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.
{
"error": {
"type": "auth_error",
"code": "E02002",
"name": "InvalidApiKey",
"message": "The API key is wrong, or was revoked.",
"doc_url": "https://docs.ponitor.com/api/errors#E02002",
"request_id": "8b1e4f0c-2d3a-4b5c-9e6f-7a8b9c0d1e2f"
}
}
Forbidden. Your team hasn't turned on the Messaging API, hasn't completed compliance (E02010) or is suspended (E02011), or the workspace can't send (E02012, E02014, E02015).
{
"error": {
"type": "permission_error",
"code": "E02010",
"name": "TeamNotVerified",
"message": "Your team hasn't completed compliance.",
"doc_url": "https://docs.ponitor.com/api/errors#E02010",
"request_id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c"
}
}
Conflict. This externalId is already on a WhatsApp message (E01007). Nothing was sent or charged. Use a new one. See Retries and externalId.
{
"error": {
"type": "conflict_error",
"code": "E01007",
"name": "Conflict",
"message": "This externalId is already on a WhatsApp message. Use a new one for an SMS.",
"doc_url": "https://docs.ponitor.com/api/errors#E01007",
"request_id": "6e7f8a9b-0c1d-4e2f-8a3b-4c5d6e7f8a9b"
}
}
Too Many Requests. Your team went over its rate limit (E01011). Nothing was sent or charged. Wait, then send the same request again with the same externalId.
Server Error. Something failed on our side (E01000). Retry with the same externalId. If the first attempt went through, you get that message back.
The message object
Get an SMS returns the same 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.