---
title: "Send a message"
method: POST
path: "/api/messaging/messages"
tags: ["Messages"]
---

# Send a message

`POST /api/messaging/messages`

Create and queue an outbound SMS or MMS message for delivery. The system determines whether the message is SMS or MMS based on the presence of `media` or the `send_as_mms` flag. The `from` number must be a purchased SignalWire phone number on the authenticated project.

#### Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Messaging_.

[Learn more about API scopes](/docs/platform/your-signalwire-api-space).

## Request body

- MessageCreateMessageRequest — Request body for sending a new SMS or MMS message.
  - `to` string, required — Destination phone number in E.164 format (`+` followed by 5-17 digits). Also accepts passthrough numbers like `988`/`+988`.
  - `from` string, required — Source phone number. Must be a purchased SignalWire phone number on the project in E.164 format, or a shortcode (5-6 digits). Verified caller IDs are not permitted.
  - `body` string — Message body text. Required if `media` is not provided. Subject to provider-specific character limits.
  - `media` string[] — Array of HTTP or HTTPS URLs for media attachments. Presence of media makes the message MMS. Maximum 8 items.
  - `send_as_mms` boolean — Force the message to be sent as MMS even when no media attachments are provided.
  - `status_callback` string, uri — A valid URL to receive message status callback events at each state change. See the [Message status callback](/docs/apis/rest/messages/webhooks/message-status-callback) webhook for the payload your URL will receive.

## Response `201`

Response returned when a message is successfully created and queued for delivery.

- MessageMessage — A message record. Returned by the create and update endpoints.
  - `id` string, uuid, required — Universal Unique Identifier.
  - `from` string, required — The source phone number.
  - `to` string, required — The destination phone number.
  - `body` string, required — The message body text. Returns an empty string when the message has been redacted.
  - `status` 'queued' | 'initiated' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'read', required — Delivery state of a message.
  - `direction` 'inbound' | 'outbound', required — The direction of a message.
  - `kind` 'sms' | 'mms', required — The kind of message.
  - `media` string[], required — Array of URLs for any media attachments on the message. Empty for SMS.
  - `number_of_segments` integer, required — Number of segments the message body was split into for delivery.
  - `error_code` string, nullable, required — Provider-specific error code if delivery failed. Null when no error occurred.
  - `error_message` string, nullable, required — Human-readable error message if delivery failed. Null when no error occurred.
  - `created_at` string, date-time, required — Date and time when the message was created.
  - `project_id` string, uuid, required — Universal Unique Identifier.
  - `status_callback_url` string, uri, nullable, required — Callback URL configured to receive message status events. Null if no callback was configured.
  - `message_uri` string, required — Relative URL for retrieving the message via the `/api/messaging/logs` endpoint.

## Other responses

- `400` — The request is invalid.
- `401` — Access is unauthorized.
- `422` — The request contains invalid parameters. See errors for details.
- `500` — An internal server error occurred.

---

[API](https://skmtc.dev/signalwire/apis/signalwire-rest-api.md) · [All operations](https://skmtc.dev/signalwire/apis/signalwire-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signalwire/apis/signalwire-rest-api/revisions/2aef612886ca?raw)