​
Welcome to the Phones Inc SMS API

The Phones Inc SMS API gives you programmatic access to two things:
  • iMessage — send and receive blue-bubble messages from a real US number, browse conversation threads and history, and get inbound messages pushed to you via signed webhooks.
  • SMS number rental — rent a temporary US number to receive a verification code.

​
Base URL

All API requests should be made to: 
https://sms.phones.inc

​
Authentication

Every request must be authenticated with your API key. You can pass it in either of two headers: 
API-KEY: sk_your_api_key
or 
Authorization: Bearer sk_your_api_key
Both forms are equivalent — use whichever fits your HTTP client best.

​
Getting Your API Key

API keys are issued by the Phones Inc team when your account is set up. Once you have a key, you can mint and revoke additional keys yourself with the key management endpoints.
Keep your API key secure! Never commit it to version control or expose it in client-side code. The full key secret is shown exactly once when a key is created.

​
Sending Requires an Assigned Number

Sending iMessages requires your account to have at least one assigned sending number. Without one, send and read endpoints return 403 with the error no iMessage number assigned to this key. Check your assigned numbers anytime with GET /v1/me. Accounts can hold multiple sending numbers. Each conversation thread lives on one number; pick the outgoing number for a new conversation with the from field on POST /v1/messages (it defaults to your first assigned number), and thread sends always use the thread’s own number.

​
Pricing

iMessage usage is billed from the same credit balance as SMS number rental:
UsageCost
Message sent0.15 credits
Reply received in a conversation you started0.05 credits
Unsolicited inbound messages (conversations you never sent to through the API) are free. If a send fails to deliver, the 0.15 credits are automatically refunded. When your balance can’t cover a send, the API returns 402 with Insufficient balance — replies to your existing conversations still come through (and are still billed), but new sends are blocked until you top up. Check your balance anytime with GET /v1/me.

​
Quick Start

Send your first iMessage: 
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"
}
The message is queued for delivery; the thread_id identifies the conversation for follow-up sends and history reads.

​
Next Steps