​
Endpoint

POST https://sms.phones.inc/v1/messages

​
Overview

Send a message to a new or existing recipient by address. The message is queued for delivery and the response identifies the conversation thread, which you can use for follow-up sends and history reads.
Sending requires your account to have at least one assigned sending number; otherwise the request returns 403. Check your numbers with GET /v1/me.
Each send costs 0.15 credits, debited when the request is accepted and refunded automatically if delivery fails. If your balance can’t cover it, the request returns 402 with Insufficient balance. See Pricing.

​
Request Body

​
to
string
required
The recipient’s address: a phone number (any common format — it is canonicalized to +1XXXXXXXXXX for US numbers) or an email-style iMessage handle.
​
text
string
required
The message body to send.
​
service
string
default:"imessage"
Which service to send over: imessage (blue bubble, the default) or sms (green bubble).
​
from
string
Which of your assigned sending numbers to send from. Defaults to your first assigned number, so you can omit it when your account holds a single number. Passing a number not assigned to your account returns 403. See your numbers with GET /v1/me.

​
Response

Returns 202 Accepted — the message is queued and delivered asynchronously.
​
ok
boolean
true when the message was queued successfully.
​
thread_id
string
ID of the conversation thread for this recipient on the sending number (created if it didn’t exist).
​
number
string
The sending number the message goes out from.
​
command_id
string
Internal ID of the queued send.
​
status
string
Always queued.
curl -X POST https://sms.phones.inc/v1/messages \
  -H "API-KEY: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "text": "Hello from the API!"
  }'

{
  "ok": true,
  "thread_id": "0b6f5c1e-8f4a-4f4b-9a2d-3a1c2b3d4e5f",
  "number": "+12315551234",
  "command_id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "status": "queued"
}