Skip to main content

Send an SMS

POST/messaging/v1/sms

Sends one SMS to one number. Ponitor returns the message, already charged and queued. Its status changes as the network reports back.

Request body​

  • #senderstringRequired
    Your approved Sender ID or Short Code.
    Example: ACME
  • #recipientstringRequired
    The phone number, in international format, with or without the +.
    Example: +231770000000
  • #workspacestringOptional
    The handle of the workspace to send from and charge, such as gbarnga-branch. Leave it out for Main. See Workspaces.
    Example: gbarnga-branch
  • #externalIdstringRequired
    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
  • #textstringOptional
    The message, 2 to 640 characters. Required unless you send template.
    Example: Your Acme order 42 is on its way.
  • #templateobjectOptional
    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
    • #idstringRequired
      otp, the only template an SMS can be sent with.
    • #parametersobjectRequired
      The values Ponitor fills in.
      2 child parameters
      • #codestringRequired
        The code, 4 to 10 digits, as a string so leading zeros stay.
      • #durationstringRequired
        How long the code works, as your customer should read it, such as "10 minutes" or "1 hour". Up to 20 characters, on one line.

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 -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."
}'

Responses​

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"
}
}

The message object​

Get an SMS returns the same 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.