---
title: "Send an SMS from a number"
method: POST
path: "/numbers/phones/{id}/messages"
tags: ["Messages", "Numbers"]
---

# Send an SMS from a number

`POST /numbers/phones/{id}/messages`

## Request

- Base URL: `https://api.mobilerun.ai`
- URL: `https://api.mobilerun.ai/numbers/phones/{id}/messages`
- Auth: HTTP bearer

Queues an SMS from one of the caller's numbers that can send. Replaying an Idempotency-Key with the same payload returns the original message, reusing it with a different payload returns 422. 409 capability_unavailable: this number cannot send right now. 422 invalid_recipient / unsupported_destination / body_too_long: the recipient or text does not fit the number. 429 daily_limit_reached: the rolling 24 h limit for the account is used up; 429 rate_limited: too many sends by the owner in a short window; 429 number_rate_limited: too many outbound sends from this number in the configured window (all sends from this number count, including those made on your behalf). 403 send_disabled: self-service SMS send is switched off.

## Path parameters

- `id` string, uuid, required

## Headers

- `idempotency-key` string: Idempotency-Key: 1-255 printable ASCII characters. Same key with a different request body is a 422 idempotency_key_reused. A retryable in-flight duplicate is a 409 with Retry-After and x-should-retry: true; a terminal duplicate is a 409 with x-should-retry: false. A replay returns the current resource state with Idempotent-Replayed: true.

## Request body

- SendPhoneMessageInput
  - `to` string, required: Recipient phone number, as E.164 or a US 10/11-digit number. Destinations the number cannot send to are rejected with 422 unsupported_destination, non-numbers with 422 invalid_recipient.
  - `body` string, required: SMS body text, up to 1600 characters (longer bodies are rejected with 400). A number's own limit may be lower and is answered 422 body_too_long.
  - `deliveryReport` boolean: Deprecated: best effort and ignored on most lines. Hosted SIM numbers return no carrier delivery report, so their messages end at `sent` and no `sms.send.delivered` event follows. Defaults to false.

## Response `202`

Outbound message queued

- object
  - `data` object, required
    - `id` string, uuid, required
    - `esimId` string, uuid, nullable, required
    - `direction` 'inbound' | 'outbound', required
    - `status` 'received' | 'queued' | 'claimed' | 'sending' | 'sent' | 'sent_unconfirmed' | 'delivered' | 'failed', required: Message status. Outbound messages move queued → sending → sent, or end at failed. `sent` means the mobile network accepted the message and is the final success status. `delivered` and `sent_unconfirmed` are kept for compatibility; current lines return no carrier delivery report, so neither is emitted.
    - `peerNumber` string, nullable, required
    - `peerKey` string, nullable, required
    - `body` string, nullable, required
    - `deliveryStatus` string, nullable, required
    - `detectedSender` string, nullable, required
    - `classification` MessageClassification, nullable, required
      - `spam` boolean, required
    - `occurredAt` string, date-time, required
    - `createdAt` string, date-time, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Self-service SMS send is not enabled (send_disabled).
- `404`: Not Found
- `409`: This number cannot send right now (capability_unavailable).
- `422`: invalid_recipient, unsupported_destination, body_too_long, or the Idempotency-Key was already used for a different request (idempotency_key_reused).
- `429`: Daily limit reached (daily_limit_reached), too many owner sends in a short window (rate_limited), or too many sends from this number (number_rate_limited).
- `500`: Internal Server Error
- `503`: The phone-number service is unavailable. See `code` for details.

## Changes

- **2026-10-27** `16cdc8c7c156`: 1 info
  - request property `deliveryReport` deprecated
- **2026-10-23** `d9f54edb041b`: 1 info
  - added the required property `data/classification` to the response with the `202` status
- **2026-10-16** `4ad548c528a8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/droidrun/apis/droidrun-cloud/changes/numbers/phones/:id/messages/post.md)

---

[API](https://skmtc.dev/droidrun/apis/droidrun-cloud.md) - [All operations](https://skmtc.dev/droidrun/apis/droidrun-cloud/llms.txt) - [OpenAPI document](https://skmtc.dev/droidrun/apis/droidrun-cloud/revisions/1cc95586c933?raw)