--- title: "SMS campaigns" description: "Marketing SMS to a segment from a published SMS template. Draft → send now or schedule, with pause, resume, cancel and reschedule. Sends run the same checks as the dashboard; consent and recipient-local quiet hours apply per recipient." url: https://www.unitpost.com/docs/api/sms-campaigns section: API reference updated: 2026-10-13 --- # SMS campaigns ## SMS campaigns > Marketing SMS to a segment from a published SMS template. Draft → send now or schedule, with pause, resume, cancel and reschedule. Sends run the same checks as the dashboard; consent and recipient-local quiet hours apply per recipient. Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/sms#sms-campaigns. ## Operations ### `GET /api/v1/sms/campaigns` List SMS campaigns Retrieve your SMS campaigns, newest first and cursor-paginated. Deleted (archived) campaigns are hidden; pass `?archived=true` to list only archived ones. Requires the `campaigns:read` capability. Reference: https://www.unitpost.com/docs/sms/get-sms-campaigns ([Markdown](https://www.unitpost.com/docs/sms/get-sms-campaigns.md)) ### `POST /api/v1/sms/campaigns` Create an SMS campaign Create an SMS campaign as a `draft`: a published SMS template sent to a segment. Omit `sender_id` for automatic routing (the best live sender per recipient), or pass an `snum_…` number to send from it. A draft always saves, even if it isn't ready yet; only an id that doesn't exist in this workspace returns `422`. `scheduled_at` saves a send time ("Send at") that a send with no `scheduled_at` uses. Check readiness with [Validate an SMS campaign](https://www.unitpost.com/docs/sms/get-sms-campaigns-id-validate), then send it with [Send an SMS campaign](https://www.unitpost.com/docs/sms/post-sms-campaigns-id-send). Requires the `campaigns:write` capability. Reference: https://www.unitpost.com/docs/sms/post-sms-campaigns ([Markdown](https://www.unitpost.com/docs/sms/post-sms-campaigns.md)) ### `GET /api/v1/sms/campaigns/{id}` Retrieve an SMS campaign Retrieve a single SMS campaign: status, routing, schedule, the reason a scheduled campaign is on `hold`, and its projected recipients. An archived campaign is still returned; an email campaign id returns `404` here. Requires the `campaigns:read` capability. Reference: https://www.unitpost.com/docs/sms/get-sms-campaigns-id ([Markdown](https://www.unitpost.com/docs/sms/get-sms-campaigns-id.md)) ### `PATCH /api/v1/sms/campaigns/{id}` Update an SMS campaign Edit a `draft` SMS campaign: name, template, segment, sender (`null` returns to automatic routing), topic, `excluded_contact_ids`, `variable_fallbacks` and the saved send time `scheduled_at` (`null` clears it). Once the campaign has been sent or scheduled, or while it is archived, edits return `409`. Pass `{ "archived": true | false }` to archive or restore it (this takes precedence over other fields). Requires the `campaigns:write` capability. Reference: https://www.unitpost.com/docs/sms/patch-sms-campaigns-id ([Markdown](https://www.unitpost.com/docs/sms/patch-sms-campaigns-id.md)) ### `DELETE /api/v1/sms/campaigns/{id}` Delete an SMS campaign Archive a draft or finished SMS campaign; its delivery history is kept and an already archived campaign returns `204` again. Restore it with `{ "archived": false }` on [Update an SMS campaign](https://www.unitpost.com/docs/sms/patch-sms-campaigns-id). A scheduled, sending or paused campaign returns `409`: cancel it first with [Cancel an SMS campaign](https://www.unitpost.com/docs/sms/post-sms-campaigns-id-cancel). Requires the `campaigns:write` capability. Reference: https://www.unitpost.com/docs/sms/delete-sms-campaigns-id ([Markdown](https://www.unitpost.com/docs/sms/delete-sms-campaigns-id.md)) ### `POST /api/v1/sms/campaigns/{id}/send` Send an SMS campaign Send a `draft` SMS campaign. Omit `scheduled_at` to use the draft's saved send time when it is still in the future (otherwise it sends now), pass `null` to send now, or a time to schedule it. API sends run the same checks as the dashboard: plan, schedule window, carrier registration and content rules, topic, and sending limits. Anything that blocks the send returns `409` with each reason in `error.details[]`: `field` names the request field to fix (`template_id`, `segment_id`, `sender_id`, `topic_id`) and `code` the reason (e.g. `template_not_published`). A sender registered for a non-marketing use case returns `422` `use_case_mismatch`, and a daily sending limit returns `429` with `Retry-After`. Consent and recipient-local quiet hours are applied per recipient: people without marketing consent are skipped, and messages that would land in quiet hours wait for the window to open. Requires the `campaigns:send` capability. Reference: https://www.unitpost.com/docs/sms/post-sms-campaigns-id-send ([Markdown](https://www.unitpost.com/docs/sms/post-sms-campaigns-id-send.md)) ### `POST /api/v1/sms/campaigns/{id}/cancel` Cancel an SMS campaign Cancel a `scheduled`, `sending` or `paused` SMS campaign. Messages already handed to the carrier are not recalled. Requires the `campaigns:send` capability. Reference: https://www.unitpost.com/docs/sms/post-sms-campaigns-id-cancel ([Markdown](https://www.unitpost.com/docs/sms/post-sms-campaigns-id-cancel.md)) ### `POST /api/v1/sms/campaigns/{id}/pause` Pause an SMS campaign Pause a `scheduled` or `sending` SMS campaign. Recipients not yet sent to wait until you resume it. Requires the `campaigns:send` capability. Reference: https://www.unitpost.com/docs/sms/post-sms-campaigns-id-pause ([Markdown](https://www.unitpost.com/docs/sms/post-sms-campaigns-id-pause.md)) ### `POST /api/v1/sms/campaigns/{id}/resume` Resume an SMS campaign Resume a `paused` SMS campaign for the recipients not yet sent to. The send checks run again, so a block that appeared while paused returns `409`. Requires the `campaigns:send` capability. Reference: https://www.unitpost.com/docs/sms/post-sms-campaigns-id-resume ([Markdown](https://www.unitpost.com/docs/sms/post-sms-campaigns-id-resume.md)) ### `POST /api/v1/sms/campaigns/{id}/reschedule` Reschedule an SMS campaign Move a `scheduled` SMS campaign to a new future `scheduled_at` inside your plan's scheduling window. Requires the `campaigns:send` capability. Reference: https://www.unitpost.com/docs/sms/post-sms-campaigns-id-reschedule ([Markdown](https://www.unitpost.com/docs/sms/post-sms-campaigns-id-reschedule.md)) ### `GET /api/v1/sms/campaigns/{id}/validate` Validate an SMS campaign Check whether an SMS campaign could send now and who it would reach, without sending anything: `can_send`, the `blockers` a send would be refused for, the `reachable` count, the skip breakdown (`no_marketing_consent`, `quiet_hours_deferred`, and the rest in `skipped_by_reason`), when a quiet-hours hold would let it start, and whether a sender's use case or a missing template variable would block the send. Rate-limited per workspace. Requires the `campaigns:read` capability. Reference: https://www.unitpost.com/docs/sms/get-sms-campaigns-id-validate ([Markdown](https://www.unitpost.com/docs/sms/get-sms-campaigns-id-validate.md)) ## Related - [SMS topics](https://www.unitpost.com/docs/api/sms-topics): SMS subscription categories recipients can opt out of, independent from email topics. STOP still opts a number out of every SMS. - [API keys](https://www.unitpost.com/docs/api/api-keys): Create and revoke the API keys your integrations authenticate with. These endpoints are session-gated (dashboard cookie + `apikeys:manage`) and NOT usable with a Bearer API key. - [Suppressions](https://www.unitpost.com/docs/api/suppressions): Address-level send blocks — the hard "never email this address" list. Combines engine-written bounce/complaint entries, your own additions, and read-only Unitpost-wide blocks.