Quickstart
Six short steps from nothing to a delivered SMS that your server is told about. Every request here is one you can paste into a terminal.
0. Get an API key
Sign in to the dashboard with your Phound account — there is no separate developer account — and create a key on
the API keys page. For this guide it needs the numbers:read,
messages:send and webhooks:manage scopes.
The key looks like ck_live_… and is shown once. Every request sends it as
Authorization: Bearer <key>.
export PHOUND_KEY=ck_live_...
Sending needs an approved 10DLC registration — US carriers only deliver business texts from registered senders.
Submit it on the dashboard's Registration page now: review usually
takes a few business days, and you can do steps 1–3 meanwhile. Until it's approved, step 4 answers
403 registration_required. More about registration
The dashboard has a built-in webhook inbox. On Webhooks, choose Use the built-in inbox, and every event lands on the Events page with its signature checked. You can skip steps 2 and 3 until you have an endpoint of your own.
1. Pick the number to send from
Your numbers live in the Account API. Ask for the ones that can send SMS:
curl "https://api.phound.app/accounts/v1/phone-numbers?capability=sms" \
-H "Authorization: Bearer $PHOUND_KEY"
const res = await fetch("https://api.phound.app/accounts/v1/phone-numbers?capability=sms", {
headers: { Authorization: `Bearer ${process.env.PHOUND_KEY}` },
});
const { data } = await res.json();
console.log(data);
import os, requests
res = requests.get(
"https://api.phound.app/accounts/v1/phone-numbers",
params={"capability": "sms"},
headers={"Authorization": f"Bearer {os.environ['PHOUND_KEY']}"},
)
print(res.json()["data"])
{ "object": "list", "has_more": false, "next_cursor": null,
"data": [ { "id": "pn_219552", "e164": "+13075222720",
"capabilities": ["voice", "sms", "mms"], "status": "active" } ] }
The e164 is what you send from in step 4 — anywhere a number is taken, the number
itself is how you name it (the id works too).
2. Register a webhook
Tell us where to send events. Your endpoint must be public HTTPS. Webhooks are managed in the Account API.
curl https://api.phound.app/accounts/v1/webhooks \
-H "Authorization: Bearer $PHOUND_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/phound/webhooks", "events": ["message.*"]}'
const res = await fetch("https://api.phound.app/accounts/v1/webhooks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PHOUND_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ url: "https://example.com/phound/webhooks", events: ["message.*"] }),
});
const webhook = await res.json();
console.log(webhook.id, webhook.secret); // store the secret now
import os, requests
res = requests.post(
"https://api.phound.app/accounts/v1/webhooks",
headers={"Authorization": f"Bearer {os.environ['PHOUND_KEY']}"},
json={"url": "https://example.com/phound/webhooks", "events": ["message.*"]},
)
webhook = res.json()
print(webhook["id"], webhook["secret"]) # store the secret now
message.* subscribes to every message event: message.received for replies and other
incoming messages, and the delivery events that follow the messages you send. To pick individual events, list them
instead, for example ["message.received", "message.failed"].
The response includes secret (whsec_…). It is never returned again, so store it now:
you need it to verify every event.
Your endpoint must answer 2xx within 10 seconds. Anything else is retried with backoff for about
three days — see Webhooks.
3. Verify the signature on every event
Events are signed per the Standard Webhooks spec, so any Standard Webhooks library can verify them. Or, in a few lines of Python:
import base64, hashlib, hmac, time
def verify(secret: str, headers: dict, body: bytes) -> bool:
msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
if abs(time.time() - int(ts)) > 300: # reject replays older than 5 minutes
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{msg_id}.{ts}.".encode() + body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
# The header may carry several signatures (during a secret rotation).
return any(
hmac.compare_digest(sig, expected)
for version, _, sig in (s.partition(",") for s in headers["webhook-signature"].split())
if version == "v1"
)
Pass body as the raw bytes you received. Parsing the JSON and serialising it again
changes the bytes, and the check fails. Webhooks has the
same check in Node.js and Go.
To check your endpoint before sending anything real, ask for a test event. It is signed like a real one and carries
data.test: true:
curl -X POST https://api.phound.app/accounts/v1/webhooks/wh_.../test \
-H "Authorization: Bearer $PHOUND_KEY" \
-H "Content-Type: application/json" \
-d '{"event": "message.sent"}'
const res = await fetch(`https://api.phound.app/accounts/v1/webhooks/${webhookId}/test`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PHOUND_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ event: "message.sent" }),
});
console.log(await res.json()); // what was sent, and what your endpoint answered
res = requests.post(
f"https://api.phound.app/accounts/v1/webhooks/{webhook_id}/test",
headers={"Authorization": f"Bearer {os.environ['PHOUND_KEY']}"},
json={"event": "message.sent"},
)
print(res.json()) # what was sent, and what your endpoint answered
The response shows exactly what was sent and what your endpoint answered: status, headers, body and timing.
4. Send a message
curl https://api.phound.app/messaging/v1/messages \
-H "Authorization: Bearer $PHOUND_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f1c2d0e-order-4471-shipped" \
-d '{"from": "+13075222720", "to": "+14155550123",
"text": "Hi Maria, your order has shipped."}'
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(), // reuse the same key if you retry
},
body: JSON.stringify({
from: "+13075222720",
to: "+14155550123",
text: "Hi Maria, your order has shipped.",
}),
});
const message = await res.json();
console.log(res.status, message.id, message.status);
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()), # reuse the same key if you retry
},
json={"from": "+13075222720", "to": "+14155550123",
"text": "Hi Maria, your order has shipped."},
)
message = res.json()
print(res.status_code, message["id"], message["status"])
to is an E.164 number, with the leading +. The Idempotency-Key is any unique
string you choose per message: if the request times out, retry with the same key and you get the
original result back rather than a second text on someone's phone.
A 202 means the carrier accepted it:
{ "id": "msg_01m3ae8f0pxc3xn1m8pbdt68gp", "object": "message",
"from": "+13075222720", "to": "+14155550123", "channel": "sms",
"status": { "group": "sent", "state": "sent", "final": false, "sequence": 2 } }
A 422 means it was refused before anything was sent. The body says why: code (for
example from_not_owned), a readable detail, and in errors[] the field at
fault.
5. Follow it to the end
Your webhook receives message.sent right away, then exactly one final event:
| Event | status.state | Meaning |
|---|---|---|
message.delivered | delivered_to_carrier |
The recipient's carrier confirmed delivery. |
message.unconfirmed | delivery_unconfirmed |
No receipt came back within 5 minutes. Many carriers never send one; the message most likely arrived — not a failure. |
message.failed | delivery_failed |
The carrier reported it undeliverable; see error. |
message.rejected | rejected, suppressed or sending_failed |
Refused — for example the recipient opted out — or couldn't be handed to the carrier; see
error. |
Events can arrive out of order and more than once. Deduplicate on the webhook-id header, and ignore an
event whose sequence is not higher than the last one you stored for that message.
You can also look a message up at any time with GET /messages/{id}. If events stop arriving,
GET /webhooks/{id}/deliveries?succeeded=false shows every failed attempt with your endpoint's response,
and POST /webhook-deliveries/{id}/retry sends one again.
Where next
- Sending messages — conversations, statuses, segments and safe retries.
- Webhooks — every event, retries, rotation and the delivery log.
- Messaging API reference — every field and error.