> ## Documentation Index > Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send an SMS from a number > 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. ## OpenAPI ````yaml /api-reference/mobilerun-numbers.yaml post /numbers/phones/{id}/messages openapi: 3.1.0 info: title: Mobilerun Numbers version: v1 servers: - description: Droidrun Cloud API url: https://api.mobilerun.ai/v1 security: - bearerAuth: [] paths: /numbers/phones/{id}/messages: post: tags: - Messages summary: Send an SMS from a number description: >- 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. operationId: sendNumberMessage parameters: - in: path name: id required: true schema: example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string - description: >- 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. in: header name: idempotency-key required: false schema: description: >- 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. example: b3f6a9f0-6f1a-4e9a-9e7a-9c9b6b6a5a3f maxLength: 255 minLength: 1 pattern: ^[\x21-\x7E]{1,255}$ type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SendPhoneMessageInput' responses: '202': content: application/json: schema: properties: data: properties: body: type: - string - 'null' createdAt: format: date-time type: string deliveryStatus: type: - string - 'null' detectedSender: type: - string - 'null' direction: enum: - inbound - outbound type: string esimId: format: uuid type: - string - 'null' id: format: uuid type: string occurredAt: format: date-time type: string peerKey: type: - string - 'null' peerNumber: type: - string - 'null' status: enum: - received - queued - claimed - sending - sent - sent_unconfirmed - delivered - failed type: string required: - id - esimId - direction - status - peerNumber - peerKey - body - deliveryStatus - detectedSender - occurredAt - createdAt type: object required: - data type: object description: Outbound message queued '400': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/MessageErrorResponse' description: Self-service SMS send is not enabled (send_disabled). '404': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/MessageErrorResponse' description: This number cannot send right now (capability_unavailable). '422': content: application/json: schema: $ref: '#/components/schemas/MessageErrorResponse' description: >- invalid_recipient, unsupported_destination, body_too_long, or the Idempotency-Key was already used for a different request (idempotency_key_reused). '429': content: application/json: schema: $ref: '#/components/schemas/MessageErrorResponse' description: >- 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': content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' description: Internal Server Error '503': content: application/json: schema: $ref: '#/components/schemas/NumberErrorResponse' description: The phone-number service is unavailable. See `code` for details. x-codeSamples: - lang: JavaScript source: >- import Mobilerun from '@mobilerun/sdk'; const client = new Mobilerun({ apiKey: process.env['MOBILERUN_CLOUD_API_KEY'], // This is the default and can be omitted }); const response = await client.numbers.messages.send('550e8400-e29b-41d4-a716-446655440000', { body: 'x', to: '+15551230001', }); console.log(response.data); - lang: Python source: |- import os from mobilerun_sdk import Mobilerun client = Mobilerun( api_key=os.environ.get("MOBILERUN_CLOUD_API_KEY"), # This is the default and can be omitted ) response = client.numbers.messages.send( id="550e8400-e29b-41d4-a716-446655440000", body="x", to="+15551230001", ) print(response.data) components: schemas: SendPhoneMessageInput: properties: body: description: >- 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. maxLength: 1600 minLength: 1 type: string deliveryReport: default: false description: Request a delivery report. Defaults to false. type: boolean to: description: >- 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. example: '+15551230001' maxLength: 32 minLength: 1 type: string required: - to - body type: object ApiErrorEnvelope: properties: code: type: string details: {} message: type: string retryAfterSeconds: type: number traceId: type: string required: - code - message type: object MessageErrorResponse: description: >- Messaging error envelope. `code` is the canonical discriminator (see `MessageErrorReason` for the code set). properties: code: $ref: '#/components/schemas/MessageErrorReason' message: type: string required: - code - message type: object NumberErrorResponse: description: >- Phone-number error envelope. `code` is the canonical discriminator (see `NumberErrorReason` for the code set). properties: code: $ref: '#/components/schemas/NumberErrorReason' message: type: string required: - code - message type: object MessageErrorReason: description: >- Stable machine-readable messaging error code. Unknown future values should be handled as a generic error with the same HTTP status. enum: - not_installed - missing_device - missing_subscription - idempotency_key_reused - send_disabled - daily_cap_exceeded - rate_limited - capability_unavailable - invalid_recipient - unsupported_destination - body_too_long - daily_limit_reached - number_rate_limited - product_disabled type: string NumberErrorReason: description: >- Stable machine-readable phone-number error code. Unknown future values should be handled as a generic error with the same HTTP status. enum: - product_disabled - not_cancellable type: string securitySchemes: bearerAuth: bearerFormat: Opaque description: Bearer token via Authorization header scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.