---
title: "Blast SMS to Audience"
method: POST
path: "/messages/blast/sms"
tags: ["Messages > blast"]
---

# Blast SMS to Audience

`POST /messages/blast/sms`

## Request

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

Send an SMS message to all contacts in an audience. <br>

Messages are distributed evenly across the provided sender phone numbers. <br>

Use the optional `schedule` parameter in `options` to schedule the blast for future delivery. When scheduled, the response will contain a `scheduleId` instead of blast details.

## Request body

- BlastSmsRequest: Send an SMS message to all contacts in an audience.
  - `audienceId` string, required: The audience ID to send the blast to. This identifier is a string that always begins with the prefix `aud_`, for example: `aud_abc123`. <br> You can create an audience via [the dashboard](https://app.pinnacle.sh/dashboard/audiences) or [API](/api-reference/audiences/create).
  - `senders` string[], required: Array of phone numbers to send from in E.164 format. <br> Messages will be distributed evenly across these senders. > **Note:** Sandbox numbers cannot be used for blasts. **Limit:** 1 min
  - `message` SMSContent, required: SMS message containing plain text only.
    - `text` string, required: Message content.
  - `options` BlastSmsOptions: Additional settings to customize SMS blast 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.

## Response `200`

Successfully queued or scheduled the SMS blast. <br>

- **Immediate blast**: Returns blast details including total recipients, messages, segments, and cost.
- **Scheduled blast**: Returns a `scheduleId` and the schedule configuration.

- union
  - BlastResponse: Response containing details about the scheduled blast.
    - `blastId` string, required: Unique identifier for the blast. This identifier is a string that always begins with the prefix `blast_`, for example: `blast_1234567890`.
    - `audienceId` string, required: The audience ID the blast was sent to. This identifier is a string that always begins with the prefix `aud_`, for example: `aud_abc123`.
    - `totalRecipients` integer, required: Total number of recipients in the audience.
    - `totalMessages` integer, required: Total number of messages to be sent.
    - `totalSegments` integer, required: Total number of message segments across all messages.
    - `totalCost` number, double, required: Total cost of the blast. For RCS blasts with a fallback configured, this reflects the actual mix of RCS and SMS/MMS pricing based on each recipient's RCS capability. For more details check the [Transactions page](https://app.pinnacle.sh/dashboard/settings/billing/transactions) and the [Audiences page](https://app.pinnacle.sh/dashboard/audiences) to see blasts.
  - ScheduledBlastResponse: Response returned when a blast is scheduled for future delivery.
    - `scheduleId` string, required: Unique identifier for the scheduled blast. This identifier is a string that always begins with the prefix `msg_sched_`, for example: `msg_sched_xxxxx`.
    - `config` ScheduledBlastResponseConfig, required: The schedule configuration for the blast.
      - `sendAt` string: When the first message will be sent.
      - `recurrence` string: AWS cron expression for recurring schedules.
      - `timezone` string: IANA timezone identifier.
      - `endDate` string: When recurring schedules will stop.

## 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.
- `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.

---

[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)