Docs / Guides

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"}'
Field
fromOne 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.
toThe other person, in E.164: a leading +, the country code, then the number — +14155550123. One recipient per message.
conversation_idInstead of from + to: reply in an existing conversation. Send one or the other, never both.
persona_idInstead of from, with to: send as one of your personas, from its default number.
textUp to 1,600 characters. Required unless you attach media.
mediaOptional. 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_referenceOptional. 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.
metadataOptional. Arbitrary JSON, echoed on the message and every event about it.
send_atOptional. Send it later — see Schedule a message.
max_segments, on_overflowOptional. 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_at is when it may no longer go: 24 hours after send_at unless you set it, 72 at most. A message that couldn't go out by then ends failed / expired instead 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 ends rejected / canceled and is never sent. A message no longer waiting is 409 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_progress with Retry-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
groupThe coarse bucket — switch on this. One of pending, sent, delivered, unconfirmed, failed, rejected. Fixed for this API version.
stateThe specific state within the group. New states can be added; treat one you don't recognise as its group.
finalWhether it can still change. Rely on this rather than on a list of states.
sequenceGoes up with every change. Discard any update whose sequence isn't higher than the one you have.
descriptionHuman-readable. For display only; never parse it.

The lifecycle of an SMS

groupstatefinalWhat happened
sentsentnoThe carrier accepted it. Waiting for a delivery receipt.
delivereddelivered_to_carrieryesThe recipient's carrier confirmed it. On a US toll number this is the best confirmation SMS can give — not proof it reached the handset.
unconfirmeddelivery_unconfirmedyesNo receipt within 5 minutes. Many carriers never send one, and the message very often did arrive. Treat it like sent, not like failed.
faileddelivery_failedyesThe carrier reported it undeliverable. error says why — recipient_unreachable or carrier_failure.
rejectedrejected, suppressedyesRefused 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.
rejectedsending_failedyesIt 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:

EncodingUsed whenOne SMSPer segment when split
GSM-7Only plain Latin letters, digits and common punctuation160 characters 153
UCS-2Any character outside GSM-7: emoji, most non-Latin scripts, smart quotes70 characters67

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
truncateCut the text to fit and send that.
rejectRefuse 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:

RequestReturns
GET /conversationsYour 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}/messagesIts messages, by when each was sent, newest first — as the app shows the thread; order=asc reads it from the beginning.
GET /messagesMessages 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.