> ## Documentation Index > Fetch the complete documentation index at: https://www.vobiz.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Launch a broadcast > Starts sending. This sends real SMS to every `pending` recipient and charges your account per segment, so call it only with your own credentials on a list you have consent to message. ## OpenAPI ````yaml openapi-sms.yaml POST /broadcasts/{id}/launch openapi: 3.0.3 info: title: Vobiz Messaging API description: > Send and receive SMS, MMS and RCS messages, buy messaging numbers, register for US 10DLC and toll-free, run broadcasts, manage conversations, opt-outs and webhooks. **Base URL:** `https://api.vobiz.ai/api/v1/sms` **Authentication:** every request needs the `X-Auth-ID` and `X-Auth-Token` headers. The account is taken from your credentials; you never put an account ID in a path or body. Field names in this API are camelCase. version: '1.0' contact: email: support@vobiz.ai url: https://vobiz.ai servers: - url: https://api.vobiz.ai/api/v1/sms description: Production security: - AuthID: [] AuthToken: [] tags: - name: Messages description: Send messages and inspect their delivery state. - name: Numbers description: >- Messaging-capable numbers on your account, inventory search, purchase and release. - name: Coverage description: Where you can send, per country. - name: Conversations description: Two-way threads between one of your numbers and a contact. - name: Opt-outs description: Numbers that must not receive messages on a channel. - name: Webhooks description: Subscriptions that deliver message and broadcast events to your server. - name: Broadcasts description: Bulk sends from an uploaded recipient list. - name: RCS Senders description: RCS sender (agent) identities and their message templates. - name: 10DLC Brands description: US 10DLC brand registration. - name: 10DLC Campaigns description: US 10DLC campaigns, toll-free verification and supporting documents. paths: /broadcasts/{id}/launch: post: tags: - Broadcasts summary: Launch a broadcast description: >- Starts sending. This sends real SMS to every `pending` recipient and charges your account per segment, so call it only with your own credentials on a list you have consent to message. Only a `draft` can be launched; it moves to `running`, or to `scheduled` when `scheduledAt` is in the future. Launch returns `422` when the template is empty, when no recipient is pending, or when a phone-number `from` is not an SMS number on your account. Each recipient is sent like `POST /messages` with the broadcast's `tag` and DLT IDs and the idempotency key `broadcast::`, so no recipient is messaged twice. operationId: launch-broadcast parameters: - name: id in: path required: true description: >- The broadcast's `id` (UUID), as returned by `POST /broadcasts` or `GET /broadcasts`. An id that is not a UUID, or that belongs to another account, returns `404` with `broadcast not found`. schema: type: string format: uuid example: 3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35 responses: '200': description: The broadcast, now `running` or `scheduled`. content: application/json: schema: $ref: '#/components/schemas/Broadcast' example: id: 3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35 accountId: MA_XXXXXXXX name: October pricing update from: '+14155550100' channel: sms template: Hi {{name}}, your refund of {{amount}} is on its way. status: running scheduledAt: null ratePerSecond: 5 tag: pricing-oct dltEntityId: '' dltHeaderId: '' dltTemplateId: '' columns: - phone - name - amount stats: total: 3 pending: 3 sent: 0 delivered: 0 failed: 0 optedOut: 0 skipped: 0 createdAt: '2026-10-12T10:30:00Z' updatedAt: '2026-10-12T11:05:10Z' startedAt: '2026-10-12T11:05:10Z' completedAt: null '401': $ref: '#/components/responses/Unauthorized' '404': description: The broadcast does not exist on your account. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: broadcast not found '409': description: The broadcast is not a draft. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: cannot launch a broadcast that is completed '422': description: >- The draft is not ready to send. Fix the template, recipients or sender and launch again. content: application/json: schema: $ref: '#/components/schemas/Error' examples: template: value: error: template is empty recipients: value: error: the broadcast has no valid recipients to send to sender: value: error: +14155550100 is not an SMS number on this account route: value: error: no SMS route for sender EXAMPLE x-codeSamples: - lang: typescript label: Node SDK source: > import { VobizClient } from "@vobiz/sdk"; const client = new VobizClient({ apiKey: "MA_XXXXXXXX", authToken: "YOUR_AUTH_TOKEN" }); await client.sms.broadcasts.launchBroadcast({ id: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35" }) - lang: python label: Python SDK source: | from vobiz import Vobiz client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN") client.sms.broadcasts.launch_broadcast( id="3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35", ) - lang: go label: Go SDK source: | import ( "context" vobiz "github.com/vobiz-ai/Vobiz-Go-SDK" "github.com/vobiz-ai/Vobiz-Go-SDK/client" "github.com/vobiz-ai/Vobiz-Go-SDK/option" "github.com/vobiz-ai/Vobiz-Go-SDK/sms" ) c := client.NewClient( option.WithAPIKey("MA_XXXXXXXX"), option.WithAuthToken("YOUR_AUTH_TOKEN"), ) request := &sms.LaunchBroadcastRequest{ ID: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35", } c.Sms.Broadcasts.LaunchBroadcast( context.TODO(), request, ) - lang: java label: Java SDK source: | import com.vobiz.api.VobizApiClient; VobizApiClient client = VobizApiClient .builder() .apiKey("MA_XXXXXXXX") .authToken("YOUR_AUTH_TOKEN") .build(); client.sms().broadcasts().launchBroadcast( "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35", LaunchBroadcastRequest .builder() .build() ); - lang: ruby label: Ruby SDK source: > require 'vobiz' client = Vobiz::Client.new(api_key: 'MA_XXXXXXXX', auth_token: 'YOUR_AUTH_TOKEN') client.sms.broadcasts.launch_broadcast(id: "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35") - lang: csharp label: C# SDK source: | using Vobiz; using Vobiz.Sms; var client = new VobizApiClient("YOUR_AUTH_TOKEN", "MA_XXXXXXXX"); await client.Sms.Broadcasts.LaunchBroadcastAsync( new LaunchBroadcastRequest { Id = "3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35" } ); - lang: php label: PHP SDK source: > sms->broadcasts->launchBroadcast( '3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35', ); components: schemas: Broadcast: type: object description: >- A bulk SMS send that renders one template for every recipient of an uploaded list and sends at a controlled rate. Its `status` moves from `draft` through `scheduled` or `running` to `completed`, `cancelled` or `failed`, and `stats` counts recipients by state. properties: id: type: string format: uuid example: 3f8d2a6e-5b1c-4e7f-a9d0-2c4b6e8f1a35 description: >- Unique identifier of the broadcast (UUID). Use it in every `/broadcasts/{id}` path. accountId: type: string description: Your Vobiz account ID (`MA_...`) that owns the broadcast. example: MA_XXXXXXXX name: type: string example: October pricing update description: >- The label you gave the broadcast, shown in the console and in listings. from: type: string description: >- The sender every message goes out from, as stored: an E.164 number, a short code or an alphanumeric sender ID. example: '+14155550100' channel: type: string enum: - sms example: sms description: The channel the broadcast sends on. Always `sms`. template: type: string description: >- The message body with `{{variable}}` placeholders, filled per recipient from the columns of the upload. Empty until you set it. example: Hi {{name}}, your refund of {{amount}} is on its way. status: type: string enum: - draft - scheduled - running - paused - completed - cancelled - failed description: >- Lifecycle state. `draft` until you launch, then `scheduled` (waiting for `scheduledAt`) or `running`. `paused` after a pause call or when `pauseReason` is set; `completed` once every recipient is processed; `cancelled` after a cancel call; `failed` when the run stopped on an error. example: draft pauseReason: type: string enum: - insufficient_balance description: >- Present only while the broadcast is paused for a reason other than your own pause call. `insufficient_balance` means the balance ran out; top up and call `POST /broadcasts/{id}/resume`. scheduledAt: type: string format: date-time nullable: true description: >- When sending starts after launch, in UTC (ISO 8601). `null` means sending starts as soon as you launch. example: null ratePerSecond: type: integer description: Maximum messages sent per second while running, from 1 to 50. example: 5 tag: type: string description: >- Your label, copied onto every message the broadcast sends. Empty string when not set. example: '' dltEntityId: type: string description: >- India (TRAI DLT). The Principal Entity ID copied onto every message. Empty string when not set. example: '' dltHeaderId: type: string description: >- India (TRAI DLT). The registered sender header ID copied onto every message. Empty string when not set. example: '' dltTemplateId: type: string description: >- India (TRAI DLT). The registered content template ID copied onto every message. Empty string when not set. example: '' columns: type: array nullable: true description: >- Column names from the latest recipient upload, as written in your file header. The first is the phone column and the rest are available as template variables. Empty until you upload recipients. items: type: string example: null stats: allOf: - $ref: '#/components/schemas/BroadcastStats' description: Recipient counts by state, recounted on every read. createdAt: type: string format: date-time example: '2026-10-12T10:30:00Z' description: When the broadcast was created (ISO 8601, UTC). updatedAt: type: string format: date-time example: '2026-10-12T10:30:00Z' description: >- When the broadcast last changed, including status changes (ISO 8601, UTC). startedAt: type: string format: date-time nullable: true description: When sending began (ISO 8601, UTC). `null` until the broadcast runs. example: null completedAt: type: string format: date-time nullable: true description: >- When the broadcast finished, either because the last recipient was processed or because it was cancelled (ISO 8601, UTC). `null` until then. example: null Error: type: object description: >- The body of every error response: a flat object with one `error` string that explains what went wrong. Use the HTTP status code to decide how to handle the error, and log `error` for diagnosis. required: - error properties: error: type: string example: 'recipient has opted out: +14155550123' description: >- Human-readable explanation of the error, for example `phoneNumber is required` or `recipient has opted out: +14155550123`. Branch on the HTTP status code rather than on this text. BroadcastStats: type: object description: >- Counts of the broadcast's stored recipients by state, recounted every time you read the broadcast. properties: total: type: integer description: >- Recipients stored on the broadcast, including opted-out ones. Invalid rows and duplicates from the upload are not stored and not counted. example: 3 pending: type: integer description: Recipients still waiting to be sent. example: 0 sent: type: integer example: 3 description: >- Recipients whose message was accepted for sending and has no delivery report yet. delivered: type: integer example: 0 description: Recipients whose message was reported delivered. failed: type: integer example: 0 description: Recipients whose message failed. Their `errorCode` says why. optedOut: type: integer description: >- Recipients excluded because the number opted out of SMS from you. They are never sent. example: 0 skipped: type: integer description: Recipients that were still pending when the broadcast was cancelled. example: 0 responses: Unauthorized: description: Missing or invalid `X-Auth-ID` / `X-Auth-Token`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing or invalid credentials securitySchemes: AuthID: type: apiKey in: header name: X-Auth-ID description: Your Vobiz account Auth ID (`MA_XXXXXXXX`). AuthToken: type: apiKey in: header name: X-Auth-Token description: Your Vobiz account Auth Token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.