Messages API

Read text messages and send SMS from your own systems. Reading needs messages:read. Sending needs messages:write.

The message object

{
  "id": "c4d5e6f7-0a1b-4c2d-8e3f-9a0b1c2d3e4f",
  "direction": "outbound",
  "from": "+16045550188",
  "to": "+14155550123",
  "body": "Your technician is on the way.",
  "status": "sent",
  "conversation_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "user_id": null,
  "error_code": null,
  "created_at": "2026-11-02T16:00:00.000Z",
  "updated_at": "2026-11-02T16:00:01.000Z"
}

List messages

GET /messages

• limit, cursor: pagination.
• direction: inbound or outbound.
• phone: only the conversation with this number.
• created_after, created_before: ISO 8601 dates.

Send a text

POST /messages

• from_number_id (required): the Dialstitch number to send from. Get ids from GET /numbers.
• to (required): the recipient's number.
• body (required): up to 1,600 characters.
• user_id: send as this user. You need it to send from someone's personal number.

curl -X POST https://dialstitch.com/api/v1/messages \
  -H "Authorization: Bearer dpk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-eta" \
  -d '{"from_number_id": "b8e2f7c4-1d3a-4e5b-8c9d-0a1b2c3d4e5f", "to": "+14155550123", "body": "Your technician is on the way."}'

• 201: sent to the carrier. The body is { "data": <message> }.
• 200: a replay. You sent the same Idempotency-Key before, so you get the first message back and nothing is sent again.
• 502: the carrier refused the message. It's saved as failed, and the response includes both the error and the failed message in data.

Idempotency keys

Add an Idempotency-Key header so a retried request can't text someone twice. Keys are 1 to 100 letters, digits or . _ : -, and they're scoped to your API key.