---
title: "Send SMS Message"
method: POST
path: "/messages/send/sms"
tags: ["Messages > sms"]
---

# Send SMS Message

`POST /messages/send/sms`

## Request

- Base URL: `https://api.pinnacle.sh`
- URL: `https://api.pinnacle.sh/messages/send/sms`
- Auth: API key in header `PINNACLE-API-KEY`

Send a SMS message immediately or schedule it for future delivery.

## Request body

- SendSmsSchema
  - `from` string, required: Phone number that sends the message in E.164 format.
  - `options` SendSmsOptions: Additional settings to customize SMS delivery.
    - `schedule` ScheduleSchema: Define when and how your message should be sent.
      - `sendAt` string, required: The date and time you want your message to be sent. - Use [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), for example: `2024-12-17T14:30:00Z`. Format: `YYYY-MM-DDThh:mm` (e.g., `2024-12-25T14:30`). - This time must be at least 5 minutes in the future. - The message will be scheduled based on the `timezone` you provide. - If you set a `recurrence` schedule, this is the start date and time for the recurring schedule.
      - `recurrence` string: AWS cron expression for recurring schedules (6 fields). <br> [Learn more about cron expressions](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-scheduled-rule-pattern.html). <br> **Examples:** - `0 10 * * ? *` - Every day at 10:00 AM - `0/30 * * * ? *` - Every 30 minutes - `0 9 ? * MON-FRI *` - Every weekday at 9:00 AM - `0 12 1 * ? *` - First day of every month at noon
      - `timezone` string: IANA timezone identifier (e.g., `America/New_York`, `UTC`). <br> Defaults to `UTC` if not specified.
      - `endDate` string: Date and time when recurring messages should stop. <br> Format: `YYYY-MM-DDThh:mm`. Required if `recurrence` is set.
    - `tracking` 'ID' | 'HIDDEN': Enable tracking on sent messages. If not provided, messages are not tracked. You will not be able to react to these messages unless you provide the [options.force](./react#request.body.options.force) field. `ID` - Append an explicit ID at the end of the message for tracking. Users will see this ID. <br> `HIDDEN` - Invisible IDs are sent with messages for tracking. Will not be visible to users but will lead to slightly longer message lengths.
  - `text` string, required: Message content.
  - `to` string, required: Recipient's phone number in E.164 format.

## Response `200`

Successfully sent or scheduled the message. <br>

Use our [/messages/:id](./get) endpoint to track your message.

- union
  - SendSmsResponse
    - `messageId` string, required: Unique identifier for the sent message. This identifier is a string that always begins with the prefix `msg_`, for example: `msg_1234567890`.
    - `segments` SendSmsResponseSegments, required: Details about how the message was segmented for sending.
      - `count` number, double, required: Number of message segments used to send this message.
      - `encoding` 'gsm7' | 'utf16', required: Encoding used for the message segments.
    - `totalCost` number, double, required: Total cost of sending the message.
    - `sender` string, required: Sender's phone number in E.164 format.
    - `recipient` string, required: Recipient's phone number in E.164 format.
    - `status` 'queued', required: Message is queued for delivery.
  - ScheduledSendResponse
    - `scheduleId` string, required: Unique identifier for the scheduled send. This identifier is a string that always begins with the prefix `msg_sched_`, for example: `msg_sched_1234567890`.
    - `config` ScheduledSendResponseConfig, required: Configuration for the scheduled message.
      - `sendAt` string, required: When the message will be sent in ISO 8601 format.
      - `recurrence` string: AWS cron expression used for recurring messages.
      - `timezone` string, required: IANA timezone identifier.
      - `endDate` string: When the recurring messages stops in ISO 8601 format.

## Other responses

- `400`: The request was unacceptable, often due to providing an invalid update. <br> Errors may originate from invalid payload or from Pinnacle's additional validation checks. For example, providing an URL that cannot be accessed, updating a campaign that is currently being reviewed, updating data that you cannot access, sending a malformed message, and so on. <br> For `Pinnacle Validation Error` inspect the `error` payload to determine the source of the failure. These errors are likely due to additional validation and business logic checks.<br> For `Request Validation Error` inspect the `description` and `errors` payload to determine the source of failure. These errors are likely due to invalid payload inside the request.
- `401`: The request lacks valid authentication credentials or the provided credentials are invalid. <br> Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint.
- `402`: Insufficient credits to complete this request. <br> This occurs when your account balance is below the required amount for processing the operation. Please add credits to your account to continue using the service.
- `403`: Your subscription does not include access to this feature. <br> This occurs when attempting to use functionality that requires a higher subscription tier. Please upgrade your subscription to access this feature.
- `404`: The requested resource could not be found. <br> This may occur if the identifier is incorrect, the resource has been deleted, or you don't have permission to access it.
- `500`: An unexpected error occurred on Pinnacle's servers while processing your request. <br> If this error persists, please contact support with the request details.
- `501`: The requested functionality is not implemented on the server. <br> This typically indicates that the feature or endpoint you attempted to access is unavailable or not yet supported.

---

[API](https://skmtc.dev/pinnacle/apis/pinnacle-2.md) - [All operations](https://skmtc.dev/pinnacle/apis/pinnacle-2/llms.txt) - [OpenAPI document](https://skmtc.dev/pinnacle/apis/pinnacle-2/revisions/45416dadab79?raw)