Sending messages
How to address a message, schedule it, check it before sending, retry safely, and follow it to its final status, or cancel it while it waits — plus reading and searching conversations.
Send one
POST /messages, with the messages:send scope. Your account needs an approved
messaging registration (10DLC) first; until then every send is refused
with 403 registration_required.
curl https://api.phound.app/messaging/v1/messages \
-H "Authorization: Bearer $PHOUND_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"from": "+13075222720", "to": "+14155550123", "text": "Your table is ready.",
"client_reference": "booking-8812"}'
import { randomUUID } from "node:crypto";
const res = await fetch("https://api.phound.app/messaging/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PHOUND_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": randomUUID(),
},
body: JSON.stringify({
from: "+13075222720",
to: "+14155550123",
text: "Your table is ready.",
client_reference: "booking-8812",
}),
});
import os, uuid, requests
res = requests.post(
"https://api.phound.app/messaging/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['PHOUND_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={"from": "+13075222720", "to": "+14155550123", "text": "Your table is ready.",
"client_reference": "booking-8812"},
)
| Field | |
|---|---|
from | One of your numbers, E.164 (its id, pn_…, works too). It must be able
to send SMS — GET https://api.phound.app/accounts/v1/phone-numbers?capability=sms lists the ones that can. |
to | The other person, in E.164: a leading +, the country code, then the
number — +14155550123. One recipient per message. |
conversation_id | Instead of from + to: reply in an existing
conversation. Send one or the other, never both. |
persona_id | Instead of from, with to: send as one of your
personas, from its default number. |
text | Up to 1,600 characters. Required unless you attach media. |
media | Optional. Up to 10 attachments, each {"url": "https://…"} with an
optional content_type and size_bytes. Attaching media sends the message as MMS, so the
sending number must be MMS-capable (from_not_mms_capable otherwise). The URL is one
POST /media returned, or a public http(s) URL of yours — see below. |
client_reference | Optional. Your own correlation string, up to 255 characters, echoed
on the message and every event about it. Not a deduplication key — that's Idempotency-Key. |
metadata | Optional. Arbitrary JSON, echoed on the message and every event about it. |
send_at | Optional. Send it later — see Schedule a message. |
max_segments, on_overflow | Optional. Cap how many SMS segments the text may take — see Message length and segments. |
You never need to create a conversation first. Sending from one of your numbers to someone new starts one; sending again to the same person from the same number continues it.
The response
202 means the message was handed to the carrier. It returns the full message:
{
"id": "msg_01m3ae8f0pxc3xn1m8pbdt68gp",
"object": "message",
"conversation_id": "conv_01m3ae8f0n5w2q7y1d0x9hcz3k",
"direction": "outbound",
"channel": "sms",
"from": "+13075222720",
"to": "+14155550123",
"text": "Your table is ready.",
"delivery_fidelity": "carrier",
"status": { "group": "sent", "state": "sent", "final": false, "sequence": 2,
"occurred_at": "2026-10-01T15:04:05Z" },
"error": null,
"client_reference": "booking-8812",
"metadata": {},
"created_at": "2026-10-01T15:04:05Z"
}
If it was refused before reaching the carrier, you get a Problem instead:
403 registration_required while your messaging
registration isn't approved, 422 for something about the request (validation_failed
with the field in errors[], or message_rejected with the reason in detail), or
500
upstream_unavailable if it couldn't be handed over at all — retry that one.
Schedule a message
Set send_at to send it later, up to 90 days ahead. A time that has already passed sends it now.
{ "from": "+13075222720", "to": "+14155550123", "text": "Reminder: your table is at 8pm tonight.",
"send_at": "2026-10-09T22:00:00Z" }
It's checked like any other send when you make the request — sender, registration, suppressions, media — and the
202 returns it with status pending / scheduled and its
send_at. Your webhooks get message.accepted. At
send_at it goes out, and from there it's like any message: message.sent, then its final
event.
expires_atis when it may no longer go: 24 hours aftersend_atunless you set it, 72 at most. A message that couldn't go out by then endsfailed/expiredinstead of arriving late.- If you suppress the recipient while it waits, it ends
rejected/suppressed. - To cancel it,
POST /messages/{id}/cancel(messages:send): it endsrejected/canceledand is never sent. A message no longer waiting is409 not_scheduled.
Check before sending
POST /messages/preview takes the same body as POST /messages and runs every check a send
would, without sending, charging or storing anything:
{
"object": "message_preview",
"would_send": false,
"resolved_from": "+13075222720",
"channel": "sms",
"segments": { "count": 2, "encoding": "UCS2", "characters": 74, "billable_units": 2 },
"encoding_escalated_by": [ { "character": "’", "offset": 9, "reason": "not_representable_in_gsm7" } ],
"estimated_cost": { "amount": "0.0158", "currency": "USD" },
"suppressions": [ { "id": "sup_…", "reason": "manual", "address": "+14155550123", … } ],
"blockers": [ { "code": "recipient_suppressed", "status": 422, … } ]
}
What would stop the send — registration, the sender, the persona, a suppression or opt-out — comes back in
blockers rather than as an error. Use it to show someone exactly what will go out, and what it costs,
before they confirm. Media URLs are checked but not downloaded.
Send a photo, video or audio (MMS)
Attach media and the message goes as MMS. Point it at a file you already host, or upload one to
POST /media first and pass what it returns:
curl https://api.phound.app/messaging/v1/media \
-H "Authorization: Bearer $PHOUND_KEY" \
-F "file=@invoice.jpg"
{ "object": "media", "url": "https://…cxstatic.com/f/cbd3be1a-e32e-4afd-96af-632f26d64c12",
"content_type": "image/jpeg", "size_bytes": 482113, "expires_at": "2026-10-12T14:03:11Z" }
curl https://api.phound.app/messaging/v1/messages \
-H "Authorization: Bearer $PHOUND_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"from": "+13075222720", "to": "+14155550123", "text": "Here's your invoice.",
"media": [{"url": "https://…cxstatic.com/f/cbd3be1a-e32e-4afd-96af-632f26d64c12", "content_type": "image/jpeg"}]}'
Files are up to 5 MB: images (GIF, JPEG, PNG, WebP), video (3GPP, MP4, MPEG, QuickTime) and audio (AMR, M4A,
MP3, WAV). The type is read from the file itself, not its name. An uploaded file is deleted at
expires_at, so send the message before then. The sending number has to be MMS-capable.
A URL of your own works too. Phound downloads it while handling the send and checks it the same way, so a file
that can't go out is refused right away with 422 (media_unreachable,
too_large or unsupported_media_type on the field). The message carries Phound's copy of
the file — the URLs in the response differ from yours, and changing your file afterwards doesn't affect it.
Retry safely with Idempotency-Key
A network timeout doesn't tell you whether the message went out. Send an Idempotency-Key header —
any string up to 255 characters, a UUID is ideal — and retry with the same key:
- Same key, same body, within 24 hours: you get the original response back, with
Idempotency-Replay: true. Nothing is sent twice. - Same key, different body:
409 idempotency_key_reuse. Bodies are compared as JSON, so key order and whitespace don't make a request different. - The first request is still running:
409 request_in_progresswithRetry-After. Wait, then retry with the same key. - The request failed with an error: the key is released, so you can fix the request or retry with the same key.
Keys are scoped to your account and the endpoint. Use a new key for each new message.
Status
Every outbound message has a status:
| Field | |
|---|---|
group | The coarse bucket — switch on this. One of
pending, sent, delivered, unconfirmed, failed,
rejected. Fixed for this API version. |
state | The specific state within the group. New states can be added; treat one you don't recognise as its group. |
final | Whether it can still change. Rely on this rather than on a list of states. |
sequence | Goes up with every change. Discard any update whose sequence isn't
higher than the one you have. |
description | Human-readable. For display only; never parse it. |
The lifecycle of an SMS
| group | state | final | What happened |
|---|---|---|---|
sent | sent | no | The carrier accepted it. Waiting for a delivery receipt. |
delivered | delivered_to_carrier | yes | The recipient's carrier confirmed it. On a US toll number this is the best confirmation SMS can give — not proof it reached the handset. |
unconfirmed | delivery_unconfirmed | yes | No receipt within 5
minutes. Many carriers never send one, and the message very often did arrive. Treat it like sent,
not like failed. |
failed | delivery_failed | yes | The carrier reported it
undeliverable. error says why — recipient_unreachable or
carrier_failure. |
rejected | rejected, suppressed | yes | Refused on
policy, compliance or billing — for example the recipient opted out (suppressed), the number needs
10DLC registration, or the account is out of funds. error says which. |
rejected | sending_failed | yes | It couldn't be handed to the carrier. |
A scheduled message starts earlier, at pending / scheduled, and can also end
failed / expired or rejected / canceled without being sent —
see Schedule a message.
If the recipient is a Phound app user, the message is delivered in the app instead: channel is
in_app and the status is delivered / delivered_to_handset right away.
Each change is pushed to your webhooks as an event; you can also poll
GET /messages/{id} (messages:read).
When the message ends in failed or rejected, error carries the same
Problem object the API uses for error responses. owner_action_required: true means someone with access
to the account has to fix something — registration, verification, funds — before retrying makes sense.
Message length and segments
Long texts are split into several SMS segments, and each segment is billed. How many characters fit depends on the encoding:
| Encoding | Used when | One SMS | Per segment when split |
|---|---|---|---|
| GSM-7 | Only plain Latin letters, digits and common punctuation | 160 characters | 153 |
| UCS-2 | Any character outside GSM-7: emoji, most non-Latin scripts, smart quotes | 70 characters | 67 |
A single character outside GSM-7 switches the whole message to UCS-2: one curly apostrophe pasted from a word
processor can turn a one-segment message into three. A few GSM-7 characters — ^ { } \ [ ~ ] | € — count
as two. Every message reports what it took in segments, and
POST /messages/preview tells you before you send, with the
characters that forced UCS-2.
To cap the cost of a text you don't control, set max_segments (1–10) and what to do when it's over:
on_overflow | |
|---|---|
truncate | Cut the text to fit and send that. |
reject | Refuse the send with 422 and too_many_segments on
/text. |
split (default) | Sending it as several messages isn't supported yet: a text over the cap
is refused with not_supported on /on_overflow. |
An MMS is one message however long its text, so the cap doesn't apply to it.
Conversations and history
Your conversations hold every SMS and MMS your numbers send and receive — through this API, or in the Phound
app — so your code sees the whole thread, not just its own part. When a recipient turns out to be a Phound user,
the message is delivered in the app (channel: "in_app"), and their replies there come back into the
same conversation. Your personal Phound app chats with other users, and team channels, are never included.
sent_via tells an outbound message's source: api for this API (the developer portal
and the MCP server send through it too), phound_app for one sent from the app. History from before
your account started using the API is imported once — the 1,000 newest messages of each of your most recent
threads — without webhook events.
A conversation belongs to a persona, not one of its numbers: messages to and from any of the persona's numbers
are one thread, as they are in the app, and an inbound message doesn't say which number it was sent to. Its
phone_number is the number it started on — the persona's default, for a thread from the app — and
replies by conversation_id go from it.
With messages:read:
| Request | Returns |
|---|---|
GET /conversations | Your conversations, newest activity first, each with its persona and
last_direction — inbound is a thread waiting on your reply. Filter by phone_number (its persona's threads),
participant, channel, or
updated_after — the cheap way to poll for what changed. |
GET /conversations/{id} | One conversation, with what a list item leaves out: the whole
contact — every number and email, and the note — and reply_check, whether a reply would go
out now and, if not, what stops it. ?expand=recent_messages includes its last 20 messages. |
GET /conversations/{id}/messages | Its messages, by when each was sent, newest first —
as the app shows the thread; order=asc reads it from the beginning. |
GET /messages | Messages across all your conversations, newest first by when each reached the API, so polling never misses one synced late — see Search. |
GET /messages/{id} | One message, with its current status. |
Lists are paged: pass limit, and while has_more is true, the
next_cursor from one page as cursor to get the next.
curl "https://api.phound.app/messaging/v1/conversations/conv_.../messages?order=asc" \
-H "Authorization: Bearer $PHOUND_KEY"
A message sent from the Phound app has from: null, and one received has to: null: the
app keeps a persona's numbers in one chat with each person, and doesn't say which of them was used.
participant.display_name and contact_id name the other person when they're in your
contacts.
Opening a conversation before the first message is rarely needed, but
POST /conversations (messages:send) does it — with phone_number,
participant. Asking for one that exists returns it with 200.
Search
GET /messages?query=… searches message text across every conversation. Each word matches as a
prefix, so it works as you type — invo finds "invoice" and "invoices". "Exact phrases"
match words in order, -word excludes one, and or matches either side. Each result has a
highlight: the text around its matches, HTML-escaped, each match in <mark>. It
combines with every other filter —
conversation_id, phone_number, participant, direction,
channel, status_group, created_after, created_before.
To find a conversation by who it's with, GET /conversations?query=… matches part of the other
person's contact name, or at least 3 digits of their number.
curl "https://api.phound.app/messaging/v1/messages?query=invoice%20-paid&direction=inbound" \
-H "Authorization: Bearer $PHOUND_KEY"
Contacts
Your contacts are the address book the Phound app keeps from your phone, served by the
Account API with the contacts:read scope:
GET https://api.phound.app/accounts/v1/contacts lists them, newest first — query matches a name or an
address, address finds who has an exact number — and GET /contacts/{id} returns one. Each has a
name, a note, and addresses: its phone numbers in E.164, and email
addresses.
They're read-only here: add and change contacts on your phone. A conversation's participant shows the name of the
contact holding their number, and participant.contact_id is that contact's id.
Receiving messages
When someone texts one of your numbers, the message is added to the conversation with them — a new one if they
haven't messaged that number before — usually within seconds, and within a minute at most. A
message.received event goes to your webhooks. It's the same message object with
direction: "inbound" and status: null: an inbound message has already arrived, so it has
no delivery status. Messages you send from the Phound app are added the same way, with
sent_via: "phound_app", and produce message.sent and their delivery events like the
API's own.
To reply, send with its conversation_id, or with from set to your number and
to set to theirs.