SMS

SMS in Pozy sends from phone numbers you buy or port into Pozy. Outbound messages go through POST /v1/sms/messages, replies land in the same Inbox as every other channel, and delivery arrives as webhooks. The platform id is sms.

This page is the summary. Number buying, porting, US carrier registration and sender IDs each have a full page in Phone, SMS & voice.

#What you can do

#Connect

There is no OAuth. SMS needs usage-based billing and an SMS-capable number:

#Sending messages

curl -X POST https://api.pozy.ai/v1/sms/messages \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reminder-appt-88213" \
  -d '{
    "from": "+14155550123",
    "to": "+13105551234",
    "text": "Reminder: your appointment is tomorrow at 10:00. Reply C to confirm."
  }'

const res = await fetch("https://api.pozy.ai/v1/sms/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": "reminder-appt-88213",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "+14155550123",
    to: "+13105551234",
    text: "Reminder: your appointment is tomorrow at 10:00. Reply C to confirm.",
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.id, data.conversationId);

import os, requests

resp = requests.post(
    "https://api.pozy.ai/v1/sms/messages",
    headers={
        "Authorization": f"Bearer {os.environ['POZY_API_KEY']}",
        "Idempotency-Key": "reminder-appt-88213",
    },
    json={
        "from": "+14155550123",
        "to": "+13105551234",
        "text": "Reminder: your appointment is tomorrow at 10:00. Reply C to confirm.",
    },
)
print(resp.json())

The response has the message id and the inbox conversationId. Send an Idempotency-Key so a retry replays the original response instead of texting twice. Reusing a key with a different body returns 422; a key that is still in flight returns 409.

To text many people, create an SMS broadcast. Its attachments go out as MMS media.

#Media requirements

#Limits

Sender IDs cannot receive replies, cannot send MMS, and cannot send to the US, Canada or Puerto Rico. Prices are per segment and set by the destination carrier after sending, so you cannot get a quote before a send.

#Opt-outs

A recipient who replies STOP is opted out by the carrier. Further sends to them return 409; they are never dropped silently. Only the recipient can opt back in, by replying START. Keep your own list in sync with List SMS opt-outs (add format=csv for a file).

#Look up a number

Look up carrier and line type returns carrierName, lineType (mobile, landline, voip, toll-free or unknown) and smsReachable. Each lookup is billed by the carrier-data provider, so run it when you clean a list, not before every send.

#Analytics

There are no post analytics for SMS. Each message reports its outcome as a webhook. Conversation volume and response times are in Inbox analytics.

#Inbox

Replies thread into one conversation per contact and number in the Inbox, with platform: "sms".

You can also reply from the inbox with Send message.

#Pricing

SMS is billed per segment by destination, plus the monthly price of each number and, in the US, the 10DLC brand and campaign fees. See Pricing for the current table.

#Errors you may see

Errors covers the error format.

#Endpoints

#Webhook events