SMS

A sender, a consent record, then the first text. Every call is on this page.

Start

A paid plan, a brand, a sender, consent, then the first text.

Open this guide on its own page

SMS is included on every paid plan and is not on the free plan. On the free plan sms.send and SMS campaign sends return 403 with limit_reached, and the error's details carry feature_not_in_plan on smsChannel, so your code can tell a plan without SMS from a counted limit. A new API key or scope doesn't change it; the reads still work. Texts spend the same monthly allowance as email, at the published rate for each country (Pricing).

SMS does not start with a domain. It starts with a brand: your legal entity, website, and a contact email on that website. Carriers approve the brand before they hand you a production number. The simulator can text verified test numbers before any of that is done.

Next is a sender: a toll-free or 10DLC number, or a Sender ID where the country allows one. The monthly lease and the one-time carrier fees are quoted before you confirm, then taken from the wallet.

A recipient needs a phone number and a consent record. Marketing texts need express consent. STOP, quiet hours, and country reach are checked before the message is billed. The first send is sms.send with to and body.

Reusable texts are SMS templates (sms.templates.create with a name and a plain-text body using {{variables}}; publish it before a campaign can send it). SMS topics (sms.topics.create) let recipients opt out of one kind of marketing text and keep the rest. They are separate from email topics, and STOP still opts a number out of every SMS.

To text a whole segment, create an SMS campaign (sms.campaigns.create with a name, a published template_id and a segment_id), check it with sms.campaigns.validate (who it will reach and anything that blocks it), then sms.campaigns.send: now, at a scheduled_at, or with no body to use the draft's saved send time. Pause, resume, cancel and reschedule work like email campaigns. An API send runs the same checks as the dashboard, and consent and quiet hours apply to each recipient.

Tag texts

Tags tell your texts apart later: which customer, feature or agent a text was for. Pass up to 10 tags on sms.send, each a { name, value } pair whose halves are 1 to 256 ASCII letters, digits, _ or - (the same rule as email tags). More than 10, or another character, is refused with 422 validation_error and nothing is sent; keep anything more in your own records under the text's id. Every SMS you read back carries its tags (received texts have none), sms.list with tag: "customer:acme" returns only the texts sent with that tag (several, comma-separated or repeated, means texts with all of them), and the sms.sent, sms.delivered, sms.failed, sms.scheduled and sms.suppressed webhooks carry them as data.tags, an object of name to value as on email events.

cURL
curl https://www.unitpost.com/api/v1/sms \
  -H "Authorization: Bearer $UNITPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{
    "to": "+14155551234",
    "body": "Your appointment is tomorrow at 3pm. Reply C to confirm.",
    "tags": [{ "name": "customer", "value": "acme" }, { "name": "flow", "value": "reminders" }]
  }'

# Later: every reminder text sent for Acme.
curl "https://www.unitpost.com/api/v1/sms?tag=customer:acme&tag=flow:reminders" \
  -H "Authorization: Bearer $UNITPOST_API_KEY" \
  -H "User-Agent: my-app/1.0"

Receive replies and answer them

People can text your toll-free, 10DLC and Canadian numbers back; Sender IDs are one-way. Subscribe a webhook to sms.received and each reply arrives with from, to (your number), body, keyword, auto_replied, looks_like_opt_out, participant_opted_out (they texted STOP and haven't texted START, so an answer would be refused), contact_id, in_reply_to (your text they answered) and received_at. Answer with sms.send to their number. Leave from out and a transactional answer goes out from the number they texted, so the conversation stays in one thread on their phone. Keywords are handled for you: STOP opts the number out (never answer it), HELP gets your registered help text, START opts it back in. When auto_replied is true the person already has the answer; otherwise reply as usual. Only an exact keyword records an opt-out: when looks_like_opt_out is true the text reads like "please stop texting me" without being one, so don't answer it automatically; have a person decide whether to record the opt-out. sms.list with participant returns the whole conversation with one number. To keep a texter, sms.addContact with the text's id makes them a contact (no consent recorded: a number isn't consent) and files their earlier texts under it. Each text you receive costs $0.008 a segment in the US and $0.004 in Canada, counted the same way as a send (GSM-7 160 characters, or 70 once it holds an emoji or other Unicode; longer texts split into 153 or 67), from the same balance as sends (STOP, HELP and START included).

Node.js
import { Unitpost, verifyWebhook } from "unitpost";

const unitpost = new Unitpost(process.env.UNITPOST_API_KEY);

// Your webhook endpoint, subscribed to sms.received. Pass the RAW body.
export async function onWebhook(rawBody: string, headers: Record<string, string>) {
  const event = verifyWebhook<{ type: string; data: SmsReceived }>({
    payload: rawBody,
    secret: process.env.UNITPOST_WEBHOOK_SECRET!, // whsec_…
    headers,
  });
  if (event.type !== "sms.received") return;
  const reply = event.data;
  if (reply.participant_opted_out || reply.auto_replied) return; // opted out (STOP), or already answered
  if (reply.looks_like_opt_out) return flagForReview(reply); // "please stop texting me": a person decides

  const { data: history } = await unitpost.sms.list({ participant: reply.from, limit: 20 });
  const answer = await yourAgent(history?.data ?? [], reply.body);

  // No `from`: the answer goes out from the number they texted.
  await unitpost.sms.send({ to: reply.from, body: answer });
}

type SmsReceived = {
  sms_id: string;
  from: string;
  to: string;
  body: string | null;
  keyword: "OPT_OUT" | "OPT_IN" | "HELP" | null;
  auto_replied: boolean;
  looks_like_opt_out: boolean;
  participant_opted_out: boolean;
  contact_id: string | null;
  in_reply_to: string | null;
  received_at: string | null;
};
  • Order a conversation by received_at: carriers don't guarantee that texts arrive in the order they were sent.
  • Replies are text: picture messages (MMS) aren't supported on two-way numbers. A reply with no text arrives with an empty body.
  • Texts to the same person go out at most about one per second, so send one longer answer rather than several quick ones.
  • Two-way works on US and Canadian numbers. A reply to a Sender ID never reaches you.

Let people sign up by text

Give a number a join keyword (sms.addJoinKeyword with a keyword and, optionally, a static segment_id and an SMS topic_id; up to 10 per number). When someone texts exactly that word, Unitpost answers "Reply YES to get our marketing texts" with the required disclosures. Their YES records verified marketing consent, makes them a contact if they aren't one, and adds the segment and topic. The keyword alone never counts as consent, and it never undoes a STOP: someone who opted out gets one reply telling them to text START. On a toll-free number they texted STOP to, nothing is sent: the carrier blocks texts from that number until they text UNSTOP, and it already told them so. STOP, HELP, START, YES and their variants can't be keywords. If the number's carrier registration doesn't list keyword opt-in, the keyword still saves and the answer carries a registration_warning: add keyword opt-in to the registration so carriers don't flag the number.

Set it up with an agent

Everything above can run with no one in the dashboard: an agent platform that sets up a number per customer, or your coding agent over MCP. The order is the dashboard's:

  • Brand: sms.createBrand (POST /sms/brands) with the legal entity, website and contact. Its missing list says what is still needed. Free.
  • Use case: sms.messagingPrograms.create with what the texts are for, how people opt in, the help and stop replies and two sample messages.
  • Files: an opt-in screenshot (purpose sms_opt_in_evidence, a PNG up to 400 KB) or a company document (sms_document, PDF, PNG or JPEG up to 3 MB) goes in once with files.create (POST /files), from a public url or base64. An agent with a terminal hands over a local file with an upload session: files.create with content_type and size_bytes, then curl -T the file to the upload.url it returns. The Node and Python SDKs do both in one call: files.upload.
  • Carriers: quote and confirm (sms.quotes.create, show the person the price, then sms.quotes.confirm): ten_dlc_brand_registration, then ten_dlc_campaign from the use case with its number, or a toll_free_number with the opt-in screenshot as opt_in_evidence_file_id. Confirming needs sms:purchase on the key, which no preset includes.
  • The monthly cap for API purchases: a workspace that pays for its own paid plan usually starts with $75 (not when a key or app of it already held sms:purchase; one its organization pays for follows the organization Owner's rules), enough to set up a toll-free number ($2) or a typical 10DLC sender ($15.50: brand, campaign, number), and even a public company's 10DLC sender with the optional brand vetting ($69.50), counted as the fee due now plus the first month of a monthly fee. A confirm over it is 403 api_spend_cap_exceeded, and one with no cap 403 api_spend_cap_not_set: nothing was charged, and nothing retries it for you. Read it with GET /v1/spend-caps; the owner raises it in Settings → Billing → SMS purchases by API, or with PATCH /v1/spend-caps from a key the owner gave spend_caps:write (no other permission changes a cap). Purchases in the dashboard never count against it.
  • Documents a Sender ID country asks for live on the brand: sms.addBrandDocument with a file_id.
  • When carriers send something back, its feedback says what (GET /sms/registrations, GET /sms/numbers). Fix the brand or the use case, then resubmit for free: sms.registrations.resubmit (a 10DLC campaign) or sms.resubmitNumber (a toll-free number). A failed number whose fee is already paid comes back with sms.registrations.requestNumber.

Taking things down is on the API too, and none of it can be undone: release a number with POST /v1/sms/numbers/{id}/release (its monthly fee ends; scheduled campaigns or queued texts block it unless force), remove a 10DLC setup that has no number with POST /v1/sms/registrations/{id}/remove, and replace an approved brand registration with POST /v1/sms/registrations/{id}/replace to correct the brand and register it again. Requesting a Sender ID still happens in the dashboard (SMS → Numbers). Every step above is also an MCP tool (sms_brands_create, files_create, sms_quotes_create, …) and a CLI command (unitpost files create --file ./optin.png).

Send transactional and marketing SMS, and track each message's delivery lifecycle. Marketing sends require recipient consent and honor recipient-local quiet hours. Included on paid plans: on the free plan, POST /sms returns 403 with limit_reached and feature_not_in_plan on smsChannel in error.details[]. Each segment is billed from the workspace's monthly sending allowance at the recipient country's published rate.

Record SMS consent

POST/api/v1/contacts/{id}/sms-consent

POST /contacts/{id}/sms-consent
curl -X POST 'https://www.unitpost.com/api/v1/contacts/con_123/sms-consent' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "sms_consent",
  "phone": "string",
  "recorded": {
    "id": "id_123",
    "action": "string",
    "source": "string",
    "occurred_at": "2026-01-01T00:00:00.000Z"
  }
}

Record an SMS opt-in or opt-out that a recipient gave you — typically a checkbox on your own signup form. This is the supported way to bring consent you already hold into Unitpost so marketing SMS is accepted for that contact. source is required: consent without recorded provenance is not consent, and the source is what makes the audit trail defensible. occurred_at may be backdated to when the recipient actually agreed (do not pretend historical consent happened just now); a future timestamp is rejected. Every call appends an immutable event, so the history is never overwritten. Recording an opt-out suppresses SMS for this contact only — it does not touch their email subscription. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body7 fields
FieldTypeDescription
actionrequiredenumopt_in | opt_out—
sourcerequiredenumweb_form | hosted_form | keyword | qr | verbal | paper | api_import | api—
purposeenummarketing | transactional—
phonestring—
occurred_atstring—
evidence_urlstring—
disclosure_versionstring—
Response · 201 fields3 fields
FieldTypeDescription
objectrequiredstring—
phonerequiredstring—
recordedrequiredobject | null—
201401404422

Request SMS opt-in confirmation

POST/api/v1/contacts/{id}/sms-opt-in-request

POST /contacts/{id}/sms-opt-in-request
curl -X POST 'https://www.unitpost.com/api/v1/contacts/con_123/sms-opt-in-request' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms",
  "id": "id_123",
  "to": "customer@example.com",
  "from": "you@yourdomain.com",
  "direction": "outbound",
  "status": "queued",
  "type": "transactional",
  "body": "string",
  "segments": 0,
  "in_reply_to": "string",
  "received_at": "2026-01-01T00:00:00.000Z",
  "looks_like_opt_out": false,
  "country": "string",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "error": {
    "code": "out_of_reach",
    "message": "string"
  },
  "failure_code": "quota_exceeded",
  "created_at": "2026-01-01T00:00:00.000Z",
  "contact_id": "contact_123",
  "participant_opted_out": false,
  "tags": [
    {
      "name": "Example",
      "value": "string"
    }
  ]
}

Text the contact "Reply YES to get our marketing texts" (double opt-in). A YES within 72 hours records a verified marketing opt-in; until then their existing consent stands. It only upgrades consent already on record: a number with none, one that opted out, or one already waiting for a reply is a 409 and nothing is sent. It sends a real text from a number they can reply to and charges your wallet, so pass an Idempotency-Key: a retry with the same key returns the same text instead of sending another. phone picks which of the contact's numbers (E.164); default its primary one. Any other body key is a 422. Requires the sms:send capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
phonestringWhich of the contact's numbers to text (E.164). Default: its primary number.
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring—
fromrequiredstring | null—
directionrequiredenumoutbound | inbound—
statusrequiredenumqueued | scheduled | sending | sent | delivered | failed | suppressed | canceled | received—
typerequiredenumtransactional | marketing—
bodyrequiredstring | null—
segmentsrequiredintegerBilled units. Outbound: segments. Inbound: the received text's segments when it was charged ($0.008 a segment in the US and $0.004 in Canada; a text charged before per-segment pricing was 1¢ flat and shows 1), else 0.
in_reply_torequiredstring | nullInbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise.
received_atrequiredstring | nullInbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound.
looks_like_opt_outrequiredbooleanInbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound.
countryrequiredstring | nullThe other party's country (ISO 3166-1 alpha-2): the recipient's on a send, the sender's on a received text. Null when the number's country isn't known.
scheduled_atrequiredstring | null—
last_errorrequiredstring | nullThe sentence for why the text failed or was skipped. Match on `failure_code` (failed) or `error.code` (suppressed), not on this text.
errorrequiredobject | nullSet on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
failure_codeenum | nullSet on `failed` messages: why it failed, as a stable code (the sentence is `last_error`). Null otherwise. Only `carrier_undelivered` (the carrier accepted the text, then could not deliver it) is billed; every other failure is not charged. Billing when a scheduled text was due: `quota_exceeded`, `overage_cap_exceeded`, `subscription_inactive`, `sms_not_in_plan` (the paid plan ended and its grace is over, or it is 100% discounted); `unsupported_country`: SMS to the country was paused; workspace holds: `workspace_suspended`, `sms_brand_blocked`; the sender: `sender_not_active`, `sender_registration_incomplete`, `sender_action_required`, `sender_use_case_mismatch`; `quiet_hours_unsatisfiable`: marketing that could not go out inside the recipient's window; ours: `channel_unavailable`, `delivery_exhausted`; `provider_rejected`: refused before any carrier; `suspected_pumping`: stopped before the carrier as suspected SMS pumping. The same code is `failed.code` on the `sms.failed` webhook.
created_atrequiredstring—
contact_idstring | nullThe contact this text is filed under (`con_…`), or null: an inbound text from a number that isn't a contact. Make one with POST /sms/{id}/contact.
participant_opted_outbooleanThe other party (the sender of an inbound text, the recipient of an outbound one) can't be texted by this workspace now: they texted STOP or the number is suppressed. A reply to them is refused (`opted_out`) until they text START or UNSTOP. As of this read.
tagsobject[]The tags the text was sent with (`tags` on `POST /sms`), in the order given. Empty for a text sent without tags and for received texts.
200400401403404409422

List SMS messages

GET/api/v1/sms

GET /sms
curl -X GET 'https://www.unitpost.com/api/v1/sms' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms",
      "id": "id_123",
      "to": "customer@example.com",
      "from": "you@yourdomain.com",
      "direction": "outbound",
      "status": "queued",
      "type": "transactional",
      "body": "string",
      "segments": 0,
      "in_reply_to": "string",
      "received_at": "2026-01-01T00:00:00.000Z",
      "looks_like_opt_out": false,
      "country": "string",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "last_error": "string",
      "error": {
        "code": "out_of_reach",
        "message": "string"
      },
      "failure_code": "quota_exceeded",
      "created_at": "2026-01-01T00:00:00.000Z",
      "contact_id": "contact_123",
      "participant_opted_out": false,
      "tags": [
        {
          "name": "Example",
          "value": "string"
        }
      ]
    }
  ]
}

Retrieve your workspace's SMS messages (outbound and inbound), newest-first and cursor-paginated. Narrow the list with direction, status, from, to, participant, contact_id, campaign_id, created_after/created_before, sender_id, and tag (the texts you sent with that tag). For a conversation with one person, pass participant with their number: it returns the texts you sent them and the replies they sent you. Use a message's id with Retrieve an SMS message to read its delivery state. Requires the sms:read capability.

Parameters16 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
directionstring · query`inbound` for replies people sent you, `outbound` for texts you sent.
statusstring · queryFilter by status. Inbound messages are `received`.
fromstring · querySender: the person's number on inbound, your number or Sender ID on outbound (recorded once the text is sent). URL-encode the `+` as `%2B`; a value starting with a digit is read as E.164.
tostring · queryRecipient: the person's number on outbound, your number on inbound.
participantstring · queryThe other party's E.164 number: matches `to` on texts you sent and `from` on replies you received, so one call returns the whole conversation.
contact_idstring · queryOnly messages with this contact (`con_…`), both directions.
campaign_idstring · queryOnly messages produced by this SMS campaign.
created_afterstring · queryOnly messages created at/after this ISO 8601 time.
created_beforestring · queryOnly messages created at/before this ISO 8601 time.
sender_idstring · queryOne of your numbers or Sender IDs (`snum_…`, from List SMS numbers): every text it sent or received, as its dashboard page lists them. Ignored with a warning when it can't apply (refused under `Unitpost-Strict: true`).
qstring · querySearch the message text; with 3 or more digits it also matches either number, as the dashboard's Messages log searches. At most 200 characters. Ignored with a warning when it can't apply (refused under `Unitpost-Strict: true`).
typestring · query`transactional` or `marketing`. Ignored with a warning when it can't apply (refused under `Unitpost-Strict: true`).
tagstring · queryOnly texts sent with this tag, written `name:value` (e.g. `customer:acme`), each half 1–256 ASCII letters, digits, `_` or `-`. Several, comma-separated (`customer:acme,flow:reminders`) or with `tag` repeated: only texts that carry every one of them. Received texts carry no tags. A value that isn't `name:value` is ignored with a warning (refused under `Unitpost-Strict: true`).
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring—
fromrequiredstring | null—
directionrequiredenumoutbound | inbound—
statusrequiredenumqueued | scheduled | sending | sent | delivered | failed | suppressed | canceled | received—
typerequiredenumtransactional | marketing—
bodyrequiredstring | null—
segmentsrequiredintegerBilled units. Outbound: segments. Inbound: the received text's segments when it was charged ($0.008 a segment in the US and $0.004 in Canada; a text charged before per-segment pricing was 1¢ flat and shows 1), else 0.
in_reply_torequiredstring | nullInbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise.
received_atrequiredstring | nullInbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound.
looks_like_opt_outrequiredbooleanInbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound.
countryrequiredstring | nullThe other party's country (ISO 3166-1 alpha-2): the recipient's on a send, the sender's on a received text. Null when the number's country isn't known.
scheduled_atrequiredstring | null—
last_errorrequiredstring | nullThe sentence for why the text failed or was skipped. Match on `failure_code` (failed) or `error.code` (suppressed), not on this text.
errorrequiredobject | nullSet on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
failure_codeenum | nullSet on `failed` messages: why it failed, as a stable code (the sentence is `last_error`). Null otherwise. Only `carrier_undelivered` (the carrier accepted the text, then could not deliver it) is billed; every other failure is not charged. Billing when a scheduled text was due: `quota_exceeded`, `overage_cap_exceeded`, `subscription_inactive`, `sms_not_in_plan` (the paid plan ended and its grace is over, or it is 100% discounted); `unsupported_country`: SMS to the country was paused; workspace holds: `workspace_suspended`, `sms_brand_blocked`; the sender: `sender_not_active`, `sender_registration_incomplete`, `sender_action_required`, `sender_use_case_mismatch`; `quiet_hours_unsatisfiable`: marketing that could not go out inside the recipient's window; ours: `channel_unavailable`, `delivery_exhausted`; `provider_rejected`: refused before any carrier; `suspected_pumping`: stopped before the carrier as suspected SMS pumping. The same code is `failed.code` on the `sms.failed` webhook.
created_atrequiredstring—
contact_idstring | nullThe contact this text is filed under (`con_…`), or null: an inbound text from a number that isn't a contact. Make one with POST /sms/{id}/contact.
participant_opted_outbooleanThe other party (the sender of an inbound text, the recipient of an outbound one) can't be texted by this workspace now: they texted STOP or the number is suppressed. A reply to them is refused (`opted_out`) until they text START or UNSTOP. As of this read.
tagsobject[]The tags the text was sent with (`tags` on `POST /sms`), in the order given. Empty for a text sent without tags and for received texts.
200401403422503

Send an SMS message

POST/api/v1/sms

POST /sms
curl -X POST 'https://www.unitpost.com/api/v1/sms' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+15551234567",
    "body": "Your code is 123456"
  }'
Response · 200
{
  "object": "sms",
  "id": "id_123",
  "to": "customer@example.com",
  "from": "you@yourdomain.com",
  "direction": "outbound",
  "status": "queued",
  "type": "transactional",
  "body": "string",
  "segments": 0,
  "in_reply_to": "string",
  "received_at": "2026-01-01T00:00:00.000Z",
  "looks_like_opt_out": false,
  "country": "string",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "error": {
    "code": "out_of_reach",
    "message": "string"
  },
  "failure_code": "quota_exceeded",
  "created_at": "2026-01-01T00:00:00.000Z",
  "contact_id": "contact_123",
  "participant_opted_out": false,
  "tags": [
    {
      "name": "Example",
      "value": "string"
    }
  ]
}

Send a single SMS — now, or at a future time by passing scheduled_at. The recipient must be a valid E.164 number. It doesn't have to be one of your contacts: a number you've never stored is sent to without creating a contact (pass create_contact to add one), and opt-outs and the suppression list still apply. Marketing sends additionally require the recipient's prior express consent on record and honor recipient-local quiet hours (they are deferred to the next allowed window, never dropped). The sender is chosen by the recipient's country — the active number or Sender ID whose reach covers it, exactly as campaigns route — unless you pin one with from (a snum_… id from List SMS numbers, or the number / Sender ID string). Pass an Idempotency-Key header to make retries safe: the same key with the same body replays the original message instead of sending (and billing) twice. Billing is per segment. Read delivery state back with Retrieve an SMS message. Requires the sms:send capability.

Parameters1 field
FieldTypeDescription
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body7 fields
FieldTypeDescription
torequiredstringRecipient phone number in E.164 format, e.g. `+15551234567`.
fromstringOptional sender to send from: a number id from `GET /sms/numbers` (`snum_…`), or the E.164 number / Sender ID string itself (e.g. `+18005550100`, `Acme`). Must belong to your workspace, be active, and be able to reach the recipient's country. Otherwise it answers `404 not_found`, `403 sender_not_approved`, or `422 sender_cannot_reach`. Omit to route automatically: a transactional text to someone who texted one of your numbers in the last 30 days goes out from that number, so a reply stays in the same thread on their phone; otherwise Unitpost picks the active sender whose reach covers the recipient's country (10DLC before toll-free for US recipients; the matching Sender ID elsewhere), exactly as campaigns do.
bodyrequiredstringMessage text. Billing is per segment (160 GSM-7 chars single-segment, 153 per segment concatenated; 70/67 for Unicode).
typeenumtransactional | marketingDefaults to `transactional`. Use `marketing` for anything promotional (offers, sales, newsletters): marketing sends require the recipient's prior express consent on record and honor recipient-local quiet hours. Sending promotional text as `transactional` skips both checks and breaks carrier rules.
scheduled_atstringTime to send at: ISO 8601 with `Z` or a `±hh:mm` offset (e.g. `2026-10-24T02:00:00Z` or `2026-10-24T09:00:00+07:00`), normalized to UTC. Omit to send immediately. A time in the past is not refused: the text goes out right away. A time in a later billing period is checked now (plan, price, country) but paid when it sends, from that period's allowance, so this period's balance does not refuse it. If the plan can't cover it then, the text ends `failed` with `failure_code` set (e.g. `quota_exceeded`), and `sms.failed` fires with the same code.
create_contactbooleanCreate a contact for this recipient if one doesn't exist yet. Defaults to false. Sends don't modify your contact list. When the recipient is already a contact, the message is attached to them either way. A contact created this way records no consent, so it can't be used for marketing sends.
tagsobject[]Labels to tell your texts apart later (which customer, feature or agent a text was for): up to 10 `{ name, value }` pairs, each half 1–256 ASCII letters, digits, `_` or `-`, the same rule as email tags. More than 10, or a character outside the rule, is `422 validation_error` and nothing is sent; keep anything more in your own records under the text's `id`. Returned as `tags` on the SMS object and in outbound `sms.*` webhooks; filter the list with `GET /sms?tag=name:value`.
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring—
fromrequiredstring | null—
directionrequiredenumoutbound | inbound—
statusrequiredenumqueued | scheduled | sending | sent | delivered | failed | suppressed | canceled | received—
typerequiredenumtransactional | marketing—
bodyrequiredstring | null—
segmentsrequiredintegerBilled units. Outbound: segments. Inbound: the received text's segments when it was charged ($0.008 a segment in the US and $0.004 in Canada; a text charged before per-segment pricing was 1¢ flat and shows 1), else 0.
in_reply_torequiredstring | nullInbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise.
received_atrequiredstring | nullInbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound.
looks_like_opt_outrequiredbooleanInbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound.
countryrequiredstring | nullThe other party's country (ISO 3166-1 alpha-2): the recipient's on a send, the sender's on a received text. Null when the number's country isn't known.
scheduled_atrequiredstring | null—
last_errorrequiredstring | nullThe sentence for why the text failed or was skipped. Match on `failure_code` (failed) or `error.code` (suppressed), not on this text.
errorrequiredobject | nullSet on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
failure_codeenum | nullSet on `failed` messages: why it failed, as a stable code (the sentence is `last_error`). Null otherwise. Only `carrier_undelivered` (the carrier accepted the text, then could not deliver it) is billed; every other failure is not charged. Billing when a scheduled text was due: `quota_exceeded`, `overage_cap_exceeded`, `subscription_inactive`, `sms_not_in_plan` (the paid plan ended and its grace is over, or it is 100% discounted); `unsupported_country`: SMS to the country was paused; workspace holds: `workspace_suspended`, `sms_brand_blocked`; the sender: `sender_not_active`, `sender_registration_incomplete`, `sender_action_required`, `sender_use_case_mismatch`; `quiet_hours_unsatisfiable`: marketing that could not go out inside the recipient's window; ours: `channel_unavailable`, `delivery_exhausted`; `provider_rejected`: refused before any carrier; `suspected_pumping`: stopped before the carrier as suspected SMS pumping. The same code is `failed.code` on the `sms.failed` webhook.
created_atrequiredstring—
contact_idstring | nullThe contact this text is filed under (`con_…`), or null: an inbound text from a number that isn't a contact. Make one with POST /sms/{id}/contact.
participant_opted_outbooleanThe other party (the sender of an inbound text, the recipient of an outbound one) can't be texted by this workspace now: they texted STOP or the number is suppressed. A reply to them is refused (`opted_out`) until they text START or UNSTOP. As of this read.
tagsobject[]The tags the text was sent with (`tags` on `POST /sms`), in the order given. Empty for a text sent without tags and for received texts.
200400401403404409422429503

SMS delivery stats

GET/api/v1/sms/stats

GET /sms/stats
curl -X GET 'https://www.unitpost.com/api/v1/sms/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_stats",
  "window_days": 0,
  "clamped_to_retention_days": 0,
  "totals": {
    "queued": 0,
    "sent": 0,
    "delivered": 0,
    "failed": 0,
    "suppressed": 0,
    "canceled": 0,
    "inbound": 0,
    "segments": 0
  },
  "rates": {
    "delivery": 0,
    "failure": 0,
    "suppression": 0
  }
}

Retrieve aggregate SMS delivery metrics for your workspace over a rolling window: how many texts were queued, sent, delivered, failed, suppressed (skipped on purpose: no consent, opted out, no sender that reaches the country) or canceled, how many replies came in, and how many segments were billed, with delivery, failure and suppression rates. There are no open or click numbers: carriers report sent, delivered and failed only. Control the window with days (1–365, default 30). For the messages behind these numbers, see List SMS messages. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
daysinteger · queryWindow size in days (1–365). Defaults to 30; values above 365 are rejected.
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredenumsms_stats—
window_daysrequiredintegerThe rolling window, in days.
clamped_to_retention_daysrequiredintegerNon-null when the requested window exceeded the plan's log retention and was clamped to this many days.
totalsrequiredobject—
ratesrequiredobjectPercentages (one decimal). delivery and failure are vs sent + delivered + failed; suppression is vs those plus suppressed.
200401403404422

List SMS brands

GET/api/v1/sms/brands

GET /sms/brands
curl -X GET 'https://www.unitpost.com/api/v1/sms/brands' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_brand",
      "id": "id_123",
      "name": "Example",
      "legal_name": "string",
      "website": "string",
      "domain": "string",
      "contact_email": "string",
      "status": "incomplete",
      "missing": [
        "string"
      ],
      "ten_dlc_verified": false,
      "tax_id_on_file": false,
      "number_count": 1,
      "editable": false,
      "dba_name": "string",
      "sender_id_name": "string",
      "vertical": "string",
      "legal_organization_type": "string",
      "registration_number_type": "string",
      "tax_country": "string",
      "stock_symbol": "string",
      "stock_exchange": "string",
      "contact": {
        "first_name": "string",
        "last_name": "string",
        "phone": "string"
      },
      "address": {
        "address1": "string",
        "address2": "string",
        "city": "string",
        "state": "string",
        "zip_code": "string",
        "iso_country_code": "string"
      },
      "revision": 0,
      "archived_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve your SMS brands and their setup status. A brand is the business identity carriers register before they will approve a phone number, so this is the endpoint to poll when you need to know whether SMS is usable yet: status reports whether you or the carrier is the blocker, and missing lists exactly what is still required. Create and edit a brand with Create an SMS brand (free); registering it with carriers is a paid order: Create an SMS purchase quote, then its confirm. Requires the sms:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields26 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringPrefixed brand id, e.g. `sbrand_…`.
namerequiredstringPublic-facing brand name.
legal_namerequiredstringRegistered legal entity name.
websiterequiredstring | nullBrand website URL.
domainrequiredstring | nullRegistrable domain derived from the website. The brand contact email must be on this domain.
contact_emailrequiredstring | null—
statusrequiredenumincomplete | ready | pending | action_required | verified | rejected | archived`incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier.
missingrequiredstring[]Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing.
ten_dlc_verifiedrequiredbooleanTrue when the 10DLC brand registration is approved.
tax_id_on_filerequiredboolean—
number_countrequiredintegerNon-released senders on this brand (phone numbers and Sender ID countries, any status).
editablerequiredbooleanFalse once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask.
dba_namestring | nullThe name the business trades under, when it isn't the legal name.
sender_id_namestring | nullThe one Sender ID the brand sends under abroad (1–11 characters).
verticalstring | nullThe brand's industry, in the carriers' words (e.g. `RETAIL`).
legal_organization_typestring | null`PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, …
registration_number_typestring | null—
tax_countrystring | null—
stock_symbolstring | null—
stock_exchangestring | null—
contactobjectWho carriers reach about the brand (the email is `contact_email`).
addressobjectThe registered business address.
revisionintegerMoves on every material change; a registration keeps the revision it was submitted with.
archived_atstring | null—
created_atrequiredstring—
200401403404422

Create an SMS brand

POST/api/v1/sms/brands

POST /sms/brands
curl -X POST 'https://www.unitpost.com/api/v1/sms/brands' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "sms_brand",
  "id": "id_123",
  "name": "Example",
  "legal_name": "string",
  "website": "string",
  "domain": "string",
  "contact_email": "string",
  "status": "incomplete",
  "missing": [
    "string"
  ],
  "ten_dlc_verified": false,
  "tax_id_on_file": false,
  "number_count": 1,
  "editable": false,
  "dba_name": "string",
  "sender_id_name": "string",
  "vertical": "string",
  "legal_organization_type": "string",
  "registration_number_type": "string",
  "tax_country": "string",
  "stock_symbol": "string",
  "stock_exchange": "string",
  "contact": {
    "first_name": "string",
    "last_name": "string",
    "phone": "string"
  },
  "address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "zip_code": "string",
    "iso_country_code": "string"
  },
  "revision": 0,
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Create a brand: the business identity carriers register before they approve a number. A draft may be partial (only name is required); missing says what is still needed. Free, with no carrier call; one brand per website domain (409). The tax id is write-only (stored encrypted, read back as tax_id_on_file). Registering the brand with carriers is a paid order (an SMS quote, then its confirm). Pass an Idempotency-Key so a retry never makes a second brand. Requires the sms:manage capability.

Parameters1 field
FieldTypeDescription
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body15 fields
FieldTypeDescription
namerequiredstringThe brand name recipients see.
websitestring | nullThe brand's website; a bare host gets https://.
contact_emailstring | nullAn address on the website's domain (carriers check).
sender_id_namestring | nullThe one Sender ID the brand sends under abroad: 1–11 letters, digits or hyphens, with a letter.
verticalstring | nullThe industry, in the carriers' words (e.g. `RETAIL`).
legal_namestring | nullThe exact registered legal name.
dba_namestring | null—
legal_organization_typestring | null`PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, …
tax_idstringThe company tax id (EIN in the US). Write-only: stored encrypted, read back as `tax_id_on_file`; it can be replaced, not removed.
registration_number_typestring | null—
tax_countrystring | nullTwo-letter ISO country code.
stock_symbolstring | null—
stock_exchangestring | null—
contactobject—
addressobject—
Response · 201 fields26 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringPrefixed brand id, e.g. `sbrand_…`.
namerequiredstringPublic-facing brand name.
legal_namerequiredstringRegistered legal entity name.
websiterequiredstring | nullBrand website URL.
domainrequiredstring | nullRegistrable domain derived from the website. The brand contact email must be on this domain.
contact_emailrequiredstring | null—
statusrequiredenumincomplete | ready | pending | action_required | verified | rejected | archived`incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier.
missingrequiredstring[]Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing.
ten_dlc_verifiedrequiredbooleanTrue when the 10DLC brand registration is approved.
tax_id_on_filerequiredboolean—
number_countrequiredintegerNon-released senders on this brand (phone numbers and Sender ID countries, any status).
editablerequiredbooleanFalse once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask.
dba_namestring | nullThe name the business trades under, when it isn't the legal name.
sender_id_namestring | nullThe one Sender ID the brand sends under abroad (1–11 characters).
verticalstring | nullThe brand's industry, in the carriers' words (e.g. `RETAIL`).
legal_organization_typestring | null`PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, …
registration_number_typestring | null—
tax_countrystring | null—
stock_symbolstring | null—
stock_exchangestring | null—
contactobjectWho carriers reach about the brand (the email is `contact_email`).
addressobjectThe registered business address.
revisionintegerMoves on every material change; a registration keeps the revision it was submitted with.
archived_atstring | null—
created_atrequiredstring—
201400401403404409422429503

Retrieve an SMS brand

GET/api/v1/sms/brands/{id}

GET /sms/brands/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/brands/sms_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_brand",
  "id": "id_123",
  "name": "Example",
  "legal_name": "string",
  "website": "string",
  "domain": "string",
  "contact_email": "string",
  "status": "incomplete",
  "missing": [
    "string"
  ],
  "ten_dlc_verified": false,
  "tax_id_on_file": false,
  "number_count": 1,
  "editable": false,
  "dba_name": "string",
  "sender_id_name": "string",
  "vertical": "string",
  "legal_organization_type": "string",
  "registration_number_type": "string",
  "tax_country": "string",
  "stock_symbol": "string",
  "stock_exchange": "string",
  "contact": {
    "first_name": "string",
    "last_name": "string",
    "phone": "string"
  },
  "address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "zip_code": "string",
    "iso_country_code": "string"
  },
  "revision": 0,
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}

One brand with every field you can edit, its status and missing list. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields26 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringPrefixed brand id, e.g. `sbrand_…`.
namerequiredstringPublic-facing brand name.
legal_namerequiredstringRegistered legal entity name.
websiterequiredstring | nullBrand website URL.
domainrequiredstring | nullRegistrable domain derived from the website. The brand contact email must be on this domain.
contact_emailrequiredstring | null—
statusrequiredenumincomplete | ready | pending | action_required | verified | rejected | archived`incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier.
missingrequiredstring[]Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing.
ten_dlc_verifiedrequiredbooleanTrue when the 10DLC brand registration is approved.
tax_id_on_filerequiredboolean—
number_countrequiredintegerNon-released senders on this brand (phone numbers and Sender ID countries, any status).
editablerequiredbooleanFalse once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask.
dba_namestring | nullThe name the business trades under, when it isn't the legal name.
sender_id_namestring | nullThe one Sender ID the brand sends under abroad (1–11 characters).
verticalstring | nullThe brand's industry, in the carriers' words (e.g. `RETAIL`).
legal_organization_typestring | null`PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, …
registration_number_typestring | null—
tax_countrystring | null—
stock_symbolstring | null—
stock_exchangestring | null—
contactobjectWho carriers reach about the brand (the email is `contact_email`).
addressobjectThe registered business address.
revisionintegerMoves on every material change; a registration keeps the revision it was submitted with.
archived_atstring | null—
created_atrequiredstring—
200401403404422

Update an SMS brand

PATCH/api/v1/sms/brands/{id}

PATCH /sms/brands/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/sms/brands/sms_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_brand",
  "id": "id_123",
  "name": "Example",
  "legal_name": "string",
  "website": "string",
  "domain": "string",
  "contact_email": "string",
  "status": "incomplete",
  "missing": [
    "string"
  ],
  "ten_dlc_verified": false,
  "tax_id_on_file": false,
  "number_count": 1,
  "editable": false,
  "dba_name": "string",
  "sender_id_name": "string",
  "vertical": "string",
  "legal_organization_type": "string",
  "registration_number_type": "string",
  "tax_country": "string",
  "stock_symbol": "string",
  "stock_exchange": "string",
  "contact": {
    "first_name": "string",
    "last_name": "string",
    "phone": "string"
  },
  "address": {
    "address1": "string",
    "address2": "string",
    "city": "string",
    "state": "string",
    "zip_code": "string",
    "iso_country_code": "string"
  },
  "revision": 0,
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Edit a brand: only the fields sent change (null clears an optional one), or send { archived } alone to archive or restore it. A brand carriers are reviewing or have approved, or with numbers attached, refuses carrier-field edits (409 brand_locked, details names each field) except those a correction request opened. Renaming the Sender ID while it is enabled in several countries is a 409 sender_id_in_use. Archiving a brand with numbers or open registrations is a 409 resource_in_use. Requires the sms:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body16 fields
FieldTypeDescription
namestring | nullThe brand name recipients see.
websitestring | nullThe brand's website; a bare host gets https://.
contact_emailstring | nullAn address on the website's domain (carriers check).
sender_id_namestring | nullThe one Sender ID the brand sends under abroad: 1–11 letters, digits or hyphens, with a letter.
verticalstring | nullThe industry, in the carriers' words (e.g. `RETAIL`).
legal_namestring | nullThe exact registered legal name.
dba_namestring | null—
legal_organization_typestring | null`PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, …
tax_idstringThe company tax id (EIN in the US). Write-only: stored encrypted, read back as `tax_id_on_file`; it can be replaced, not removed.
registration_number_typestring | null—
tax_countrystring | nullTwo-letter ISO country code.
stock_symbolstring | null—
stock_exchangestring | null—
contactobject—
addressobject—
archivedbooleanArchive (`true`) or restore (`false`) the brand; send it alone.
Response · 200 fields26 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringPrefixed brand id, e.g. `sbrand_…`.
namerequiredstringPublic-facing brand name.
legal_namerequiredstringRegistered legal entity name.
websiterequiredstring | nullBrand website URL.
domainrequiredstring | nullRegistrable domain derived from the website. The brand contact email must be on this domain.
contact_emailrequiredstring | null—
statusrequiredenumincomplete | ready | pending | action_required | verified | rejected | archived`incomplete` and `action_required` need the customer to act in the dashboard; `pending` is waiting on the carrier.
missingrequiredstring[]Human-readable list of what is still required before this brand can back a number. Empty when nothing is missing.
ten_dlc_verifiedrequiredbooleanTrue when the 10DLC brand registration is approved.
tax_id_on_filerequiredboolean—
number_countrequiredintegerNon-released senders on this brand (phone numbers and Sender ID countries, any status).
editablerequiredbooleanFalse once the brand is locked: carriers approved or are reviewing its 10DLC registration, or senders are registered with its details. Locked brands are corrected only when carriers ask.
dba_namestring | nullThe name the business trades under, when it isn't the legal name.
sender_id_namestring | nullThe one Sender ID the brand sends under abroad (1–11 characters).
verticalstring | nullThe brand's industry, in the carriers' words (e.g. `RETAIL`).
legal_organization_typestring | null`PRIVATE_PROFIT`, `PUBLIC_PROFIT`, `NON_PROFIT`, `GOVERNMENT`, …
registration_number_typestring | null—
tax_countrystring | null—
stock_symbolstring | null—
stock_exchangestring | null—
contactobjectWho carriers reach about the brand (the email is `contact_email`).
addressobjectThe registered business address.
revisionintegerMoves on every material change; a registration keeps the revision it was submitted with.
archived_atstring | null—
created_atrequiredstring—
200400401403404409422429503

List SMS phone numbers

GET/api/v1/sms/numbers

GET /sms/numbers
curl -X GET 'https://www.unitpost.com/api/v1/sms/numbers' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_number",
      "id": "id_123",
      "phone_number": "string",
      "type": "toll_free",
      "status": "pending",
      "is_default": false,
      "country": "string",
      "two_way": false,
      "reach": [
        "string"
      ],
      "brand_id": "brand_123",
      "use_case": {
        "name": "Example",
        "category": "string"
      },
      "action_required_reason": "string",
      "feedback": [
        {
          "reason": "string",
          "description": "string",
          "link": "string"
        }
      ],
      "sender_id_group": {
        "name": "Example",
        "brand_id": "brand_123",
        "countries": [
          {
            "country": "string",
            "status": "pending"
          }
        ]
      },
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve your SMS sending identities: phone numbers and alphanumeric Sender IDs. Only entries with status: "active" can send; a ten_dlc number has no phone_number until carriers approve the registration, a long_code is a local number issued outside the US (Canada today: country: "CA", reach: ["CA"], no carrier registration, use_case: null), and a simulator number only delivers to verified test destinations. use_case is what carriers approved the number to send. A sender_id entry is one country of a Sender ID: the identity is ONE string per brand enabled per country, the list returns one entry per (Sender ID, country), and every entry carries sender_id_group with the whole country set so you can group them. Order a number with an SMS quote and its confirm, and give one up with Release an SMS number; a Sender ID is still requested in the dashboard. Requires the sms:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringPrefixed number id, e.g. `snum_…`.
phone_numberrequiredstring | nullE.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval.
typerequiredenumtoll_free | ten_dlc | long_code | sender_id | simulator`long_code` is a local number issued outside the US (today: Canada, `country: "CA"`, reach `["CA"]`; instant, no carrier registration). `sender_id` is an alphanumeric Sender ID (one entry per enabled country; see `sender_id_group`). `simulator` only delivers to verified test destinations; it is not a production sender.
statusrequiredenumpending | action_required | active | rejected | releasedOnly `active` numbers can send.
is_defaultrequiredbooleanInformational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag.
countryrequiredstring | nullISO-3166 alpha-2 country the number was issued in (`US` for toll-free and 10DLC, `CA` for a Canadian long code). Null until recorded.
two_wayrequiredbooleanWhether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs $0.008 a segment in the US and $0.004 in Canada. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator.
reachrequiredstring[]ISO-3166 alpha-2 countries this number can deliver to. US toll-free and 10DLC numbers reach `["US"]` only; a Canadian long code reaches `["CA"]` only. A recipient outside this list is skipped before send (status `suppressed`, not billed) rather than forwarded best-effort from a shared identity. Empty while the country is unknown.
brand_idrequiredstring | nullThe brand this number is registered under.
use_caserequiredobject | nullWhat carriers approved this number to send. Required for approval; submitted with the number.
action_required_reasonrequiredstring | nullSet when status is `action_required` (what to fix: carrier feedback, why a submission failed, or a request that never reached the registry) or `rejected`.
feedbackobject[] | nullWhat carriers sent back, item by item, when a toll-free verification needs changes (`action_required`); null otherwise. Fix it on the brand or the messaging program, then POST /sms/numbers/{id}/resubmit (ADR-0159).
sender_id_grouprequiredobject | nullPresent on `sender_id` entries only. A Sender ID is ONE identity per brand enabled per country: the list still returns one entry per (Sender ID, country) so existing integrations keep working, and every entry of the same identity carries the same `sender_id_group` describing the whole set.
created_atrequiredstring—
200401403404422

Retrieve an SMS message

GET/api/v1/sms/{id}

GET /sms/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/sms_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms",
  "id": "id_123",
  "to": "customer@example.com",
  "from": "you@yourdomain.com",
  "direction": "outbound",
  "status": "queued",
  "type": "transactional",
  "body": "string",
  "segments": 0,
  "in_reply_to": "string",
  "received_at": "2026-01-01T00:00:00.000Z",
  "looks_like_opt_out": false,
  "country": "string",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "error": {
    "code": "out_of_reach",
    "message": "string"
  },
  "failure_code": "quota_exceeded",
  "created_at": "2026-01-01T00:00:00.000Z",
  "contact_id": "contact_123",
  "participant_opted_out": false,
  "tags": [
    {
      "name": "Example",
      "value": "string"
    }
  ]
}

Retrieve one SMS message's current status, delivery state, and segment count by id. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathThe SMS message id (`sms_…`).
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring—
fromrequiredstring | null—
directionrequiredenumoutbound | inbound—
statusrequiredenumqueued | scheduled | sending | sent | delivered | failed | suppressed | canceled | received—
typerequiredenumtransactional | marketing—
bodyrequiredstring | null—
segmentsrequiredintegerBilled units. Outbound: segments. Inbound: the received text's segments when it was charged ($0.008 a segment in the US and $0.004 in Canada; a text charged before per-segment pricing was 1¢ flat and shows 1), else 0.
in_reply_torequiredstring | nullInbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise.
received_atrequiredstring | nullInbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound.
looks_like_opt_outrequiredbooleanInbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound.
countryrequiredstring | nullThe other party's country (ISO 3166-1 alpha-2): the recipient's on a send, the sender's on a received text. Null when the number's country isn't known.
scheduled_atrequiredstring | null—
last_errorrequiredstring | nullThe sentence for why the text failed or was skipped. Match on `failure_code` (failed) or `error.code` (suppressed), not on this text.
errorrequiredobject | nullSet on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
failure_codeenum | nullSet on `failed` messages: why it failed, as a stable code (the sentence is `last_error`). Null otherwise. Only `carrier_undelivered` (the carrier accepted the text, then could not deliver it) is billed; every other failure is not charged. Billing when a scheduled text was due: `quota_exceeded`, `overage_cap_exceeded`, `subscription_inactive`, `sms_not_in_plan` (the paid plan ended and its grace is over, or it is 100% discounted); `unsupported_country`: SMS to the country was paused; workspace holds: `workspace_suspended`, `sms_brand_blocked`; the sender: `sender_not_active`, `sender_registration_incomplete`, `sender_action_required`, `sender_use_case_mismatch`; `quiet_hours_unsatisfiable`: marketing that could not go out inside the recipient's window; ours: `channel_unavailable`, `delivery_exhausted`; `provider_rejected`: refused before any carrier; `suspected_pumping`: stopped before the carrier as suspected SMS pumping. The same code is `failed.code` on the `sms.failed` webhook.
created_atrequiredstring—
contact_idstring | nullThe contact this text is filed under (`con_…`), or null: an inbound text from a number that isn't a contact. Make one with POST /sms/{id}/contact.
participant_opted_outbooleanThe other party (the sender of an inbound text, the recipient of an outbound one) can't be texted by this workspace now: they texted STOP or the number is suppressed. A reply to them is refused (`opted_out`) until they text START or UNSTOP. As of this read.
tagsobject[]The tags the text was sent with (`tags` on `POST /sms`), in the order given. Empty for a text sent without tags and for received texts.
200401403404

Cancel or reschedule an SMS

PATCH/api/v1/sms/{id}

PATCH /sms/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/sms/sms_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "cancel": true
  }'
Response · 200
{
  "object": "sms",
  "id": "id_123",
  "to": "customer@example.com",
  "from": "you@yourdomain.com",
  "direction": "outbound",
  "status": "queued",
  "type": "transactional",
  "body": "string",
  "segments": 0,
  "in_reply_to": "string",
  "received_at": "2026-01-01T00:00:00.000Z",
  "looks_like_opt_out": false,
  "country": "string",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "error": {
    "code": "out_of_reach",
    "message": "string"
  },
  "failure_code": "quota_exceeded",
  "created_at": "2026-01-01T00:00:00.000Z",
  "contact_id": "contact_123",
  "participant_opted_out": false,
  "tags": [
    {
      "name": "Example",
      "value": "string"
    }
  ]
}

Cancel a scheduled or queued SMS (its reserved credit is refunded), or move a scheduled one to a new send time with scheduled_at. Send exactly one of cancel: true or scheduled_at. Only a text the carrier has not been handed can be changed — afterwards this returns 409, as it does for a text that belongs to a campaign. Quiet hours still apply to the new time. Look up the current state first with Retrieve an SMS message. Requires the sms:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathThe SMS message id (`sms_…`).
Request body2 fields
FieldTypeDescription
cancelbooleanCancel a `queued` or `scheduled` text. Its reserved credit is refunded (a text due in a later billing period has not been charged yet).
scheduled_atstringMove a `scheduled` text to this future time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC. A text moved into a later billing period is refunded now and paid when it sends; a text is never charged twice.
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring—
fromrequiredstring | null—
directionrequiredenumoutbound | inbound—
statusrequiredenumqueued | scheduled | sending | sent | delivered | failed | suppressed | canceled | received—
typerequiredenumtransactional | marketing—
bodyrequiredstring | null—
segmentsrequiredintegerBilled units. Outbound: segments. Inbound: the received text's segments when it was charged ($0.008 a segment in the US and $0.004 in Canada; a text charged before per-segment pricing was 1¢ flat and shows 1), else 0.
in_reply_torequiredstring | nullInbound only: your text this reply answers (`sms_…`), when the carrier says which. Null otherwise.
received_atrequiredstring | nullInbound only: when the reply reached Unitpost. Order a conversation by this; carriers don't guarantee order. Null on outbound.
looks_like_opt_outrequiredbooleanInbound only: the text reads like a request to stop texting ("please stop texting me") but was not an opt-out keyword, so no opt-out was recorded. Decide whether to record one (POST /v1/contacts/{id}/sms-consent, action opt_out). False for an exact keyword such as STOP (already recorded) and on outbound.
countryrequiredstring | nullThe other party's country (ISO 3166-1 alpha-2): the recipient's on a send, the sender's on a received text. Null when the number's country isn't known.
scheduled_atrequiredstring | null—
last_errorrequiredstring | nullThe sentence for why the text failed or was skipped. Match on `failure_code` (failed) or `error.code` (suppressed), not on this text.
errorrequiredobject | nullSet on `suppressed` messages: the stable skip reason and its sentence. Null otherwise.
failure_codeenum | nullSet on `failed` messages: why it failed, as a stable code (the sentence is `last_error`). Null otherwise. Only `carrier_undelivered` (the carrier accepted the text, then could not deliver it) is billed; every other failure is not charged. Billing when a scheduled text was due: `quota_exceeded`, `overage_cap_exceeded`, `subscription_inactive`, `sms_not_in_plan` (the paid plan ended and its grace is over, or it is 100% discounted); `unsupported_country`: SMS to the country was paused; workspace holds: `workspace_suspended`, `sms_brand_blocked`; the sender: `sender_not_active`, `sender_registration_incomplete`, `sender_action_required`, `sender_use_case_mismatch`; `quiet_hours_unsatisfiable`: marketing that could not go out inside the recipient's window; ours: `channel_unavailable`, `delivery_exhausted`; `provider_rejected`: refused before any carrier; `suspected_pumping`: stopped before the carrier as suspected SMS pumping. The same code is `failed.code` on the `sms.failed` webhook.
created_atrequiredstring—
contact_idstring | nullThe contact this text is filed under (`con_…`), or null: an inbound text from a number that isn't a contact. Make one with POST /sms/{id}/contact.
participant_opted_outbooleanThe other party (the sender of an inbound text, the recipient of an outbound one) can't be texted by this workspace now: they texted STOP or the number is suppressed. A reply to them is refused (`opted_out`) until they text START or UNSTOP. As of this read.
tagsobject[]The tags the text was sent with (`tags` on `POST /sms`), in the order given. Empty for a text sent without tags and for received texts.
200401403404409422502

List a brand's documents

GET/api/v1/sms/brands/{id}/documents

GET /sms/brands/{id}/documents
curl -X GET 'https://www.unitpost.com/api/v1/sms/brands/sms_123/documents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_brand_document",
      "id": "id_123",
      "brand_id": "brand_123",
      "kind": "registration_certificate",
      "carrier": "string",
      "country": "string",
      "label": "string",
      "input": "file",
      "filename": "string",
      "content_type": "string",
      "size_bytes": 1,
      "text_value": "string",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The brand's current company documents (ADR-0115): one per slot (kind + carrier), plus a country's own version of a shared one (country). Sender ID countries and document-gated registrations read them; a request that lacks one is refused naming it. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
brand_idrequiredstring—
kindrequiredenumregistration_certificate | letter_of_authorization | proof_of_sender_id_connection | signatory_id | emirates_id | signatory_passport | establishment_card | power_of_attorney | business_license | tax_document | regulatory_license | carrier_registration_form | opt_in_screenshot | business_number—
carrierrequiredstring | nullThe slot's variant: which carrier or form a letter is addressed to (e.g. `ooredoo`), or null.
countryrequiredstring | nullSet when this is one country's own version of a shared document (ADR-0115): it goes to that country only, in place of the shared file. Null for the shared file.
labelrequiredstringWhat the document is, in words: "Letter of authorization — Ooredoo (Qatar)".
inputrequiredenumfile | text—
filenamerequiredstring | null—
content_typerequiredstring | null—
size_bytesrequiredinteger | null—
text_valuerequiredstring | null`business_number` only.
created_atrequiredstring—
200401403404422

Add a brand document

POST/api/v1/sms/brands/{id}/documents

POST /sms/brands/{id}/documents
curl -X POST 'https://www.unitpost.com/api/v1/sms/brands/sms_123/documents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "sms_brand_document",
  "id": "id_123",
  "brand_id": "brand_123",
  "kind": "registration_certificate",
  "carrier": "string",
  "country": "string",
  "label": "string",
  "input": "file",
  "filename": "string",
  "content_type": "string",
  "size_bytes": 1,
  "text_value": "string",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Add a document to the brand's library: a file kind takes file_id (Create a file, purpose sms_document), business_number takes text. A document in an occupied slot replaces the current one (kept only while a registration under review sent it). country makes it one country's own version of a shared document. The same checks as the dashboard (the slot's own file rule, a brand that isn't archived). Send an Idempotency-Key so a retry adds one document. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body5 fields
FieldTypeDescription
kindrequiredenumregistration_certificate | letter_of_authorization | proof_of_sender_id_connection | signatory_id | emirates_id | signatory_passport | establishment_card | power_of_attorney | business_license | tax_document | regulatory_license | carrier_registration_form | opt_in_screenshot | business_numberThe document slot. File kinds: `registration_certificate`, `letter_of_authorization`, `proof_of_sender_id_connection`, `signatory_id`, `emirates_id`, `signatory_passport`, `establishment_card`, `power_of_attorney`, `business_license`, `tax_document`, `regulatory_license`, `carrier_registration_form`, `opt_in_screenshot`. Text kinds: `business_number`. A document in an occupied slot replaces the current one (the old one is kept only while a registration under review pinned it).
carrierstringThe slot's variant, for documents addressed to one carrier (a letter of authorization for `ooredoo`). A Sender ID refusal names it.
countrystringMake this one country's own version of a shared document (ADR-0115): it goes to that country only. Refused for a slot only one country reads.
file_idstringA file kind: a file made with `POST /files`, purpose `sms_document` (PDF, PNG or JPEG, up to 3 MB; a slot can take less, e.g. Singapore's letter is a PNG up to 400 KB) or `sms_opt_in_evidence` for `opt_in_screenshot`.
textstringA text kind (`business_number`).
Response · 201 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
brand_idrequiredstring—
kindrequiredenumregistration_certificate | letter_of_authorization | proof_of_sender_id_connection | signatory_id | emirates_id | signatory_passport | establishment_card | power_of_attorney | business_license | tax_document | regulatory_license | carrier_registration_form | opt_in_screenshot | business_number—
carrierrequiredstring | nullThe slot's variant: which carrier or form a letter is addressed to (e.g. `ooredoo`), or null.
countryrequiredstring | nullSet when this is one country's own version of a shared document (ADR-0115): it goes to that country only, in place of the shared file. Null for the shared file.
labelrequiredstringWhat the document is, in words: "Letter of authorization — Ooredoo (Qatar)".
inputrequiredenumfile | text—
filenamerequiredstring | null—
content_typerequiredstring | null—
size_bytesrequiredinteger | null—
text_valuerequiredstring | null`business_number` only.
created_atrequiredstring—
201400401403404409413415422429

Retrieve a brand document

GET/api/v1/sms/brands/{id}/documents/{documentId}

GET /sms/brands/{id}/documents/{documentId}
curl -X GET 'https://www.unitpost.com/api/v1/sms/brands/sms_123/documents/documentId_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_brand_document",
  "id": "id_123",
  "brand_id": "brand_123",
  "kind": "registration_certificate",
  "carrier": "string",
  "country": "string",
  "label": "string",
  "input": "file",
  "filename": "string",
  "content_type": "string",
  "size_bytes": 1,
  "text_value": "string",
  "created_at": "2026-01-01T00:00:00.000Z"
}

One current document of the brand. Requires the sms:read capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
documentIdrequiredstring · path—
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
brand_idrequiredstring—
kindrequiredenumregistration_certificate | letter_of_authorization | proof_of_sender_id_connection | signatory_id | emirates_id | signatory_passport | establishment_card | power_of_attorney | business_license | tax_document | regulatory_license | carrier_registration_form | opt_in_screenshot | business_number—
carrierrequiredstring | nullThe slot's variant: which carrier or form a letter is addressed to (e.g. `ooredoo`), or null.
countryrequiredstring | nullSet when this is one country's own version of a shared document (ADR-0115): it goes to that country only, in place of the shared file. Null for the shared file.
labelrequiredstringWhat the document is, in words: "Letter of authorization — Ooredoo (Qatar)".
inputrequiredenumfile | text—
filenamerequiredstring | null—
content_typerequiredstring | null—
size_bytesrequiredinteger | null—
text_valuerequiredstring | null`business_number` only.
created_atrequiredstring—
200401403404422

Remove a brand document

DELETE/api/v1/sms/brands/{id}/documents/{documentId}

DELETE /sms/brands/{id}/documents/{documentId}
curl -X DELETE 'https://www.unitpost.com/api/v1/sms/brands/sms_123/documents/documentId_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_brand_document",
  "id": "id_123",
  "deleted": true,
  "file_kept": false
}

Remove a document from the brand. Its file is deleted, unless a registration sent it to a regulator (file_kept: kept as the record of what they received). Refused (409 conflict) while a Sender ID registration that sent it is under review. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
documentIdrequiredstring · path—
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
deletedrequiredboolean—
file_keptrequiredbooleanA registration sent this file to a regulator, so it is kept as the record of what they received (not on the brand any more).
200401403404409422429

Get a brand document download URL

GET/api/v1/sms/brands/{id}/documents/{documentId}/url

GET /sms/brands/{id}/documents/{documentId}/url
curl -X GET 'https://www.unitpost.com/api/v1/sms/brands/sms_123/documents/documentId_123/url' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_brand_document_url",
  "url": "https://example.com",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

A 5-minute signed link to one document's file. A document that identifies a person (signatory_id, emirates_id, signatory_passport) needs sms:manage. A text document has no file (404). Requires the sms:read capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
documentIdrequiredstring · path—
Response · 200 fields3 fields
FieldTypeDescription
objectrequiredstring—
urlrequiredstringA signed link to the file. It is a credential: fetch it now, don't share or log it.
expires_atrequiredstringThe link stops working at this time (5 minutes).
200401403404422503

Resubmit a toll-free verification

POST/api/v1/sms/numbers/{id}/resubmit

POST /sms/numbers/{id}/resubmit
curl -X POST 'https://www.unitpost.com/api/v1/sms/numbers/sms_123/resubmit' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_number_resubmission",
  "number_id": "number_123",
  "status": "resubmitted",
  "resubmitted": true
}

Resubmit a toll-free number's verification carriers sent back (action_required; feedback on List SMS numbers), or that failed before review. The form is composed again from the number's brand and a messaging program (default: the one it was registered from), so fix what carriers flagged there first. The evidence on file is reused unless opt_in_evidence_file_id replaces it; when carriers flagged the evidence, a new file (or reuse_opt_in_evidence) is required. Free while the number's monthly fee is committed, else 409 quote_required. Flagged values resent unchanged are refused (flagged_fields_unchanged) unless acknowledge_unchanged. Takes an Idempotency-Key. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body6 fields
FieldTypeDescription
messaging_program_idstringThe messaging program (`prog_…`) the corrected use case, samples and opt-in come from; fix what carriers flagged there (or on the brand) first. Defaults to the program the number was registered from.
opt_in_evidence_file_idstringNew opt-in evidence (POST /files, purpose `sms_opt_in_evidence`). Required when carriers flagged the evidence, unless `reuse_opt_in_evidence`.
reuse_opt_in_evidencebooleanSend the evidence on file again although carriers flagged it (it was fixed where it lives, e.g. the page it shows changed).
business_registration_document_file_idstringA new business registration document (POST /files, purpose `sms_document`, up to 2 MB): required when carriers flagged it.
consent_source_urlstringThe public https page where people opt in.
acknowledge_unchangedbooleanResubmit fields carriers flagged unchanged, because the cause was fixed outside Unitpost. Without it they're refused (`flagged_fields_unchanged`).
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
number_idrequiredstring—
statusrequiredstringThe verification went back to carriers; the number reads `pending` on GET /sms/numbers until they answer.
resubmittedrequiredboolean—
200400401403404409413415422429502

Retrieve an SMS number

GET/api/v1/sms/numbers/{id}

GET /sms/numbers/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/numbers/sms_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_number",
  "id": "id_123",
  "phone_number": "string",
  "type": "toll_free",
  "status": "pending",
  "is_default": false,
  "country": "string",
  "two_way": false,
  "reach": [
    "string"
  ],
  "brand_id": "brand_123",
  "use_case": {
    "name": "Example",
    "category": "string"
  },
  "action_required_reason": "string",
  "feedback": [
    {
      "reason": "string",
      "description": "string",
      "link": "string"
    }
  ],
  "sender_id_group": {
    "name": "Example",
    "brand_id": "brand_123",
    "countries": [
      {
        "country": "string",
        "status": "pending"
      }
    ]
  },
  "created_at": "2026-01-01T00:00:00.000Z"
}

One number or one country of a Sender ID (snum_…), read as List SMS numbers reads it: its status, what carriers sent back (feedback) and its use case. Read a resubmit, a retry or a release back with it. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringPrefixed number id, e.g. `snum_…`.
phone_numberrequiredstring | nullE.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval.
typerequiredenumtoll_free | ten_dlc | long_code | sender_id | simulator`long_code` is a local number issued outside the US (today: Canada, `country: "CA"`, reach `["CA"]`; instant, no carrier registration). `sender_id` is an alphanumeric Sender ID (one entry per enabled country; see `sender_id_group`). `simulator` only delivers to verified test destinations; it is not a production sender.
statusrequiredenumpending | action_required | active | rejected | releasedOnly `active` numbers can send.
is_defaultrequiredbooleanInformational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag.
countryrequiredstring | nullISO-3166 alpha-2 country the number was issued in (`US` for toll-free and 10DLC, `CA` for a Canadian long code). Null until recorded.
two_wayrequiredbooleanWhether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs $0.008 a segment in the US and $0.004 in Canada. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator.
reachrequiredstring[]ISO-3166 alpha-2 countries this number can deliver to. US toll-free and 10DLC numbers reach `["US"]` only; a Canadian long code reaches `["CA"]` only. A recipient outside this list is skipped before send (status `suppressed`, not billed) rather than forwarded best-effort from a shared identity. Empty while the country is unknown.
brand_idrequiredstring | nullThe brand this number is registered under.
use_caserequiredobject | nullWhat carriers approved this number to send. Required for approval; submitted with the number.
action_required_reasonrequiredstring | nullSet when status is `action_required` (what to fix: carrier feedback, why a submission failed, or a request that never reached the registry) or `rejected`.
feedbackobject[] | nullWhat carriers sent back, item by item, when a toll-free verification needs changes (`action_required`); null otherwise. Fix it on the brand or the messaging program, then POST /sms/numbers/{id}/resubmit (ADR-0159).
sender_id_grouprequiredobject | nullPresent on `sender_id` entries only. A Sender ID is ONE identity per brand enabled per country: the list still returns one entry per (Sender ID, country) so existing integrations keep working, and every entry of the same identity carries the same `sender_id_group` describing the whole set.
created_atrequiredstring—
200401403404422

List a number's join keywords

GET/api/v1/sms/numbers/{id}/join-keywords

GET /sms/numbers/{id}/join-keywords
curl -X GET 'https://www.unitpost.com/api/v1/sms/numbers/sms_123/join-keywords' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "sms_join_keyword",
      "id": "id_123",
      "number_id": "number_123",
      "keyword": "string",
      "segment_id": "segment_123",
      "topic_id": "topic_123",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": false,
  "registration_warning": "string"
}

Text-to-join: the words people can text this number to sign up. registration_warning is set when the number's carrier registration doesn't list keyword opt-in, so carriers could flag the sign-ups. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring`sjk_…`.
number_idrequiredstringThe number (`snum_…`) people text the keyword to.
keywordrequiredstringAs you wrote it. A text matches it whatever the case and surrounding punctuation.
segment_idrequiredstring | nullThe static segment (`seg_…`) a confirmed texter joins, or null.
topic_idrequiredstring | nullThe SMS topic a confirmed texter is subscribed to, or null.
created_atrequiredstring—
200401403404422

Add a join keyword

POST/api/v1/sms/numbers/{id}/join-keywords

POST /sms/numbers/{id}/join-keywords
curl -X POST 'https://www.unitpost.com/api/v1/sms/numbers/sms_123/join-keywords' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_join_keyword",
  "id": "id_123",
  "number_id": "number_123",
  "keyword": "string",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "created_at": "2026-01-01T00:00:00.000Z",
  "registration_warning": "string"
}

A text that is exactly this word (any case) gets the double opt-in request ("Reply YES to get … texts"). The YES records marketing consent, makes the texter a contact if they aren't one, and adds them to segment_id (a static segment) and/or topic_id (an SMS topic). A keyword is never consent by itself and never lifts a STOP: an opted-out texter is told to text START. STOP, HELP, START, YES and their variants are refused; at most 10 per number; only numbers people can text back. Adding the same keyword again answers it (200), so a retry is safe. Requires the sms:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
keywordrequiredstringOne word of 2–20 letters or digits, such as JOIN. STOP, HELP, START, YES and their variants are refused.
segment_idstringA static segment (`seg_…`) to add confirmed texters to.
topic_idstringAn SMS topic to subscribe confirmed texters to.
Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring`sjk_…`.
number_idrequiredstringThe number (`snum_…`) people text the keyword to.
keywordrequiredstringAs you wrote it. A text matches it whatever the case and surrounding punctuation.
segment_idrequiredstring | nullThe static segment (`seg_…`) a confirmed texter joins, or null.
topic_idrequiredstring | nullThe SMS topic a confirmed texter is subscribed to, or null.
created_atrequiredstring—
registration_warningrequiredstring | nullSet when the number's carrier registration doesn't list texting a keyword as a way to opt in: carriers can flag sign-ups its registration didn't declare, so add keyword opt-in to its use case and resubmit. Null otherwise.
200201400401403404409422

Remove a join keyword

DELETE/api/v1/sms/numbers/{id}/join-keywords/{keywordId}

DELETE /sms/numbers/{id}/join-keywords/{keywordId}
curl -X DELETE 'https://www.unitpost.com/api/v1/sms/numbers/sms_123/join-keywords/keywordId_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

The keyword stops answering. People who already joined keep their consent, contact and memberships. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
keywordIdrequiredstring · pathThe keyword (`sjk_…`).
204401403404

Release an SMS number

POST/api/v1/sms/numbers/{id}/release

POST /sms/numbers/{id}/release
curl -X POST 'https://www.unitpost.com/api/v1/sms/numbers/sms_123/release' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_number",
  "id": "id_123",
  "phone_number": "string",
  "type": "toll_free",
  "status": "pending",
  "is_default": false,
  "country": "string",
  "two_way": false,
  "reach": [
    "string"
  ],
  "brand_id": "brand_123",
  "use_case": {
    "name": "Example",
    "category": "string"
  },
  "action_required_reason": "string",
  "feedback": [
    {
      "reason": "string",
      "description": "string",
      "link": "string"
    }
  ],
  "sender_id_group": {
    "name": "Example",
    "brand_id": "brand_123",
    "countries": [
      {
        "country": "string",
        "status": "pending"
      }
    ]
  },
  "created_at": "2026-01-01T00:00:00.000Z"
}

Give a toll-free, 10DLC or Canadian local number, or one country of a Sender ID, back to the carrier. PERMANENT: it stops sending at once, reads released from then on and can't be had back; its monthly fee ends with it (no proration). A 10DLC number's campaign registration goes with it. Refused while an automation uses it (resource_in_use) and, unless force, while campaigns are scheduled on it or texts are queued through it (sender_release_blocked, one error.details[] entry per kind of blocker). Works on any plan. Releasing an already released number answers it; the carrier finishes the release within minutes. Takes an Idempotency-Key. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
forcebooleanRelease although campaigns are scheduled on this number or texts are queued through it (the 409 `sender_release_blocked` lists them): those sends fail as "sender not active". An automation that uses the number still blocks the release (`resource_in_use`).
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringPrefixed number id, e.g. `snum_…`.
phone_numberrequiredstring | nullE.164 number. Null while a 10DLC registration is still in review; the number is assigned on approval.
typerequiredenumtoll_free | ten_dlc | long_code | sender_id | simulator`long_code` is a local number issued outside the US (today: Canada, `country: "CA"`, reach `["CA"]`; instant, no carrier registration). `sender_id` is an alphanumeric Sender ID (one entry per enabled country; see `sender_id_group`). `simulator` only delivers to verified test destinations; it is not a production sender.
statusrequiredenumpending | action_required | active | rejected | releasedOnly `active` numbers can send.
is_defaultrequiredbooleanInformational: the workspace's first or primary number. Sends route by the recipient's country, not by this flag.
countryrequiredstring | nullISO-3166 alpha-2 country the number was issued in (`US` for toll-free and 10DLC, `CA` for a Canadian long code). Null until recorded.
two_wayrequiredbooleanWhether people can text this number: once it is active, a text to it fires the `sms.received` webhook and costs $0.008 a segment in the US and $0.004 in Canada. True for US toll-free and 10DLC numbers and Canadian long codes (two-way is offered in the US and Canada only); false for Sender IDs, which are one-way, and for the simulator.
reachrequiredstring[]ISO-3166 alpha-2 countries this number can deliver to. US toll-free and 10DLC numbers reach `["US"]` only; a Canadian long code reaches `["CA"]` only. A recipient outside this list is skipped before send (status `suppressed`, not billed) rather than forwarded best-effort from a shared identity. Empty while the country is unknown.
brand_idrequiredstring | nullThe brand this number is registered under.
use_caserequiredobject | nullWhat carriers approved this number to send. Required for approval; submitted with the number.
action_required_reasonrequiredstring | nullSet when status is `action_required` (what to fix: carrier feedback, why a submission failed, or a request that never reached the registry) or `rejected`.
feedbackobject[] | nullWhat carriers sent back, item by item, when a toll-free verification needs changes (`action_required`); null otherwise. Fix it on the brand or the messaging program, then POST /sms/numbers/{id}/resubmit (ADR-0159).
sender_id_grouprequiredobject | nullPresent on `sender_id` entries only. A Sender ID is ONE identity per brand enabled per country: the list still returns one entry per (Sender ID, country) so existing integrations keep working, and every entry of the same identity carries the same `sender_id_group` describing the whole set.
created_atrequiredstring—
200400401403404409422429

Add a texter as a contact

POST/api/v1/sms/{id}/contact

POST /sms/{id}/contact
curl -X POST 'https://www.unitpost.com/api/v1/sms/sms_123/contact' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "contact",
  "id": "id_123",
  "email": "customer@example.com",
  "phone": "string",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "unsubscribe_reason": "USER",
  "custom_fields": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Make the sender of a received text a contact, or file the text under the contact that already has the number. Phone only: no name and no consent (texting a number isn't consent to marketing). Every earlier text with that number that no contact holds is filed under the contact too, so contact_id reads it from then on. Answers the contact: 201 when it is new, 200 when it existed. It counts against the plan's contacts (403 limit_reached when full). A number that texted STOP stays opted out. A text you sent is refused (409). Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200201400401403404409422503

SMS templates

Reusable plain-text SMS bodies with per-recipient {{variables}}. Draft → published like email templates; only published templates can be sent by an SMS campaign.

List SMS templates

GET/api/v1/sms/templates

GET /sms/templates
curl -X GET 'https://www.unitpost.com/api/v1/sms/templates' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_template",
      "id": "id_123",
      "name": "Example",
      "body": "string",
      "status": "draft",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve your SMS templates, cursor-paginated. An SMS template is a plain-text body with the same {{variable}} placeholders email templates use, filled per recipient at send time. Only published templates can be used by an SMS campaign. Requires the templates:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
bodyrequiredstring—
statusrequiredenumdraft | published—
created_atrequiredstring—
updated_atrequiredstring—
200401403404422

Create an SMS template

POST/api/v1/sms/templates

POST /sms/templates
curl -X POST 'https://www.unitpost.com/api/v1/sms/templates' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "sms_template",
  "id": "id_123",
  "name": "Example",
  "body": "string",
  "status": "draft",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create an SMS template as a draft. body may be empty for a draft (it must be filled before publishing) and is capped at 10 SMS segments (1,530 GSM-7 characters). Publish it with { "status": "published" } on Update an SMS template. Requires the templates:write capability.

Request body2 fields
FieldTypeDescription
namerequiredstring—
bodystring—
Response · 201 fields7 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
bodyrequiredstring—
statusrequiredenumdraft | published—
created_atrequiredstring—
updated_atrequiredstring—
201401403404422

Retrieve an SMS template

GET/api/v1/sms/templates/{id}

GET /sms/templates/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/templates/tmpl_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_template",
  "id": "id_123",
  "name": "Example",
  "body": "string",
  "status": "draft",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single SMS template, including its body. An email template id returns 404 here. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
bodyrequiredstring—
statusrequiredenumdraft | published—
created_atrequiredstring—
updated_atrequiredstring—
200401403404

Update an SMS template

PATCH/api/v1/sms/templates/{id}

PATCH /sms/templates/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/sms/templates/tmpl_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_template",
  "id": "id_123",
  "name": "Example",
  "body": "string",
  "status": "draft",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update an SMS template's name, body or status. A published template must have a message: publishing a blank body, or clearing the body of a published template, is refused with 422. While an active SMS campaign uses a published template, editing its body or moving it back to draft is refused with 409; unpublishing is also refused while a live automation sends it. Requires the templates:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
namestring—
bodystring—
statusenumdraft | published—
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
bodyrequiredstring—
statusrequiredenumdraft | published—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Delete an SMS template

DELETE/api/v1/sms/templates/{id}

DELETE /sms/templates/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/sms/templates/tmpl_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Permanently delete an SMS template. Refused with 409 while any campaign references it, and with resource_in_use while a live automation sends it. Requires the templates:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404409

Get an SMS template's usage

GET/api/v1/sms/templates/{id}/usage

GET /sms/templates/{id}/usage
curl -X GET 'https://www.unitpost.com/api/v1/sms/templates/tmpl_123/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_template_usage",
  "template_id": "template_123",
  "live_campaigns": [
    {
      "id": "id_123",
      "name": "Example",
      "status": "queued"
    }
  ],
  "live_automations": [
    {
      "id": "id_123",
      "name": "Example",
      "status": "queued"
    }
  ],
  "pending_sends": 0,
  "system_locked": false,
  "can_edit_content": false,
  "content_blocked_reason": "string",
  "can_unpublish": false,
  "unpublish_blocked_reason": "string"
}

What uses an SMS template, and whether a change would be accepted now: its live campaigns and automations, queued texts, and can_edit_content / can_unpublish with the reason when not. Read it before an edit or delete. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
template_idrequiredstring—
live_campaignsrequiredobject[]—
live_automationsrequiredobject[]—
pending_sendsrequiredinteger—
system_lockedrequiredboolean—
can_edit_contentrequiredboolean—
content_blocked_reasonrequiredstring | null—
can_unpublishrequiredboolean—
unpublish_blocked_reasonrequiredstring | null—
200401403404422

Send a test of an SMS template

POST/api/v1/sms/templates/{id}/test-send

POST /sms/templates/{id}/test-send
curl -X POST 'https://www.unitpost.com/api/v1/sms/templates/tmpl_123/test-send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_template_test_send",
  "sms_id": "sms_123"
}

Fill the template's {{variables}} and send ONE test text to to: the simulator or a number your workspace verified (403 for any other number). A real text, billed like any; from sender_id or routed by the destination's country. Every variable needs a value (422). Pass an Idempotency-Key so a retry never texts twice. Rate limited per workspace. Requires the sms:send capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body3 fields
FieldTypeDescription
torequiredstringA simulator number (`+14254147755` delivers, `+14254147167` fails) or one of GET /sms/test-destinations' verified numbers (E.164).
variablesobjectValues for the template's `{{variables}}`; every one must be filled.
sender_idstringSend from this live sender (`snum_…`); default: routed like any text.
Response · 200 fields2 fields
FieldTypeDescription
objectrequiredstring—
sms_idrequiredstringThe test text (`sms_…`); read it with GET /sms/{id}.
200400401402403404409422429503

SMS messaging programs

What your SMS registrations are built from: the reusable purpose, opt-in, help and stop copy and sample messages a registration copies when a person submits it. Writing a program never changes a registration. Registrations, vetting and numbers are bought through a quote and its confirm (sms:purchase, within the owner's monthly API spend cap); identity documents, a toll-free number and releasing a number stay in the dashboard.

List messaging programs

GET/api/v1/sms/messaging-programs

GET /sms/messaging-programs
curl -X GET 'https://www.unitpost.com/api/v1/sms/messaging-programs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "name": "Example",
      "description": "string",
      "message_type": "transactional",
      "canonical_purpose": "string",
      "frequency_disclosure": "string",
      "opt_in_type": "string",
      "opt_in_workflow": "string",
      "opt_in_confirmation": "string",
      "help_message": "string",
      "stop_message": "string",
      "terms_url": "https://example.com",
      "privacy_url": "https://example.com",
      "monthly_volume": "string",
      "sample_messages": [
        "string"
      ],
      "embedded_links": false,
      "embedded_link_sample": "string",
      "embedded_phones": false,
      "age_gated": false,
      "provider_overrides": {
        "toll_free": {
          "use_case_category": "string"
        },
        "ten_dlc": {
          "use_case": "string",
          "sub_use_cases": [
            "string"
          ]
        }
      },
      "recipe_id": "recipe_123",
      "consent_setup_id": "consent_setup_123",
      "object": "sms_messaging_program",
      "id": "id_123",
      "recipe_version": 0,
      "revision": 0,
      "readiness": {
        "ready": false,
        "missing": [
          "string"
        ]
      },
      "archived_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Your messaging programs: what a sender registration says your texts are for, how people opt in, the help and stop replies and sample messages. Registrations copy a program when submitted; writing a program never changes one. archived=true includes archived ones. Requires the sms:read capability.

Parameters4 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
archivedstring · query`true` includes archived programs.
Response · 200 fields29 fields
FieldTypeDescription
namerequiredstring—
descriptionstring | null—
message_typerequiredenumtransactional | marketing—
canonical_purposestring | null—
frequency_disclosurestring | null—
opt_in_typestring | null—
opt_in_workflowstring | null—
opt_in_confirmationstring | null—
help_messagestring | null—
stop_messagestring | null—
terms_urlstring | null—
privacy_urlstring | null—
monthly_volumestring | null—
sample_messagesrequiredstring[]—
embedded_linksrequiredboolean—
embedded_link_samplestring | null—
embedded_phonesrequiredboolean—
age_gatedrequiredboolean—
provider_overridesobject | null—
recipe_idrequiredstring | null—
consent_setup_idstring | nullA consent setup (`cset_…`) this workspace has.
objectrequiredstring—
idrequiredstring—
recipe_versionrequiredinteger | null—
revisionrequiredintegerMoves on a material change; registrations keep the revision they copied.
readinessrequiredobjectWhether the program has what a registration needs; `missing` names the fields still to fill (the wizard's own check).
archived_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404422

Create a messaging program

POST/api/v1/sms/messaging-programs

POST /sms/messaging-programs
curl -X POST 'https://www.unitpost.com/api/v1/sms/messaging-programs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "name": "Example",
  "description": "string",
  "message_type": "transactional",
  "canonical_purpose": "string",
  "frequency_disclosure": "string",
  "opt_in_type": "string",
  "opt_in_workflow": "string",
  "opt_in_confirmation": "string",
  "help_message": "string",
  "stop_message": "string",
  "terms_url": "https://example.com",
  "privacy_url": "https://example.com",
  "monthly_volume": "string",
  "sample_messages": [
    "string"
  ],
  "embedded_links": false,
  "embedded_link_sample": "string",
  "embedded_phones": false,
  "age_gated": false,
  "provider_overrides": {
    "toll_free": {
      "use_case_category": "string"
    },
    "ten_dlc": {
      "use_case": "string",
      "sub_use_cases": [
        "string"
      ]
    }
  },
  "recipe_id": "recipe_123",
  "consent_setup_id": "consent_setup_123",
  "object": "sms_messaging_program",
  "id": "id_123",
  "recipe_version": 0,
  "revision": 0,
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ]
  },
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a program (name required). Each field is checked by the carriers' rules (the dashboard's own): lengths, help and stop replies that are a sentence and not just a keyword, links to a real web address (no localhost, bare IP or other scheme). Pass an Idempotency-Key so a retry never makes a second one. Requires the sms:manage capability.

Parameters1 field
FieldTypeDescription
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body21 fields
FieldTypeDescription
namerequiredstring—
descriptionstring | null—
message_typeenumtransactional | marketing—
canonical_purposestring | null—
frequency_disclosurestring | null—
opt_in_typestring | null—
opt_in_workflowstring | null—
opt_in_confirmationstring | null—
help_messagestring | null—
stop_messagestring | null—
terms_urlstring | null—
privacy_urlstring | null—
monthly_volumestring | null—
sample_messagesstring[]—
embedded_linksboolean—
embedded_link_samplestring | null—
embedded_phonesboolean—
age_gatedboolean—
provider_overridesobject | null—
recipe_idenumACCOUNT_NOTIFICATIONS | SECURITY_ALERTS | ONE_TIME_PASSCODES | ORDER_UPDATES | APPOINTMENT_REMINDERS | CUSTOMER_SUPPORT | MARKETING_PROMOTIONS | OTHER_CUSTOMThe compliance recipe the program follows; its version is the recipe's current one. Left out, it's derived from `canonical_purpose`.
consent_setup_idstring | nullA consent setup (`cset_…`) this workspace has.
Response · 201 fields29 fields
FieldTypeDescription
namerequiredstring—
descriptionstring | null—
message_typerequiredenumtransactional | marketing—
canonical_purposestring | null—
frequency_disclosurestring | null—
opt_in_typestring | null—
opt_in_workflowstring | null—
opt_in_confirmationstring | null—
help_messagestring | null—
stop_messagestring | null—
terms_urlstring | null—
privacy_urlstring | null—
monthly_volumestring | null—
sample_messagesrequiredstring[]—
embedded_linksrequiredboolean—
embedded_link_samplestring | null—
embedded_phonesrequiredboolean—
age_gatedrequiredboolean—
provider_overridesobject | null—
recipe_idrequiredstring | null—
consent_setup_idstring | nullA consent setup (`cset_…`) this workspace has.
objectrequiredstring—
idrequiredstring—
recipe_versionrequiredinteger | null—
revisionrequiredintegerMoves on a material change; registrations keep the revision they copied.
readinessrequiredobjectWhether the program has what a registration needs; `missing` names the fields still to fill (the wizard's own check).
archived_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

Retrieve a messaging program

GET/api/v1/sms/messaging-programs/{id}

GET /sms/messaging-programs/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/messaging-programs/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "name": "Example",
  "description": "string",
  "message_type": "transactional",
  "canonical_purpose": "string",
  "frequency_disclosure": "string",
  "opt_in_type": "string",
  "opt_in_workflow": "string",
  "opt_in_confirmation": "string",
  "help_message": "string",
  "stop_message": "string",
  "terms_url": "https://example.com",
  "privacy_url": "https://example.com",
  "monthly_volume": "string",
  "sample_messages": [
    "string"
  ],
  "embedded_links": false,
  "embedded_link_sample": "string",
  "embedded_phones": false,
  "age_gated": false,
  "provider_overrides": {
    "toll_free": {
      "use_case_category": "string"
    },
    "ten_dlc": {
      "use_case": "string",
      "sub_use_cases": [
        "string"
      ]
    }
  },
  "recipe_id": "recipe_123",
  "consent_setup_id": "consent_setup_123",
  "object": "sms_messaging_program",
  "id": "id_123",
  "recipe_version": 0,
  "revision": 0,
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ]
  },
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve one program, archived ones too. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields29 fields
FieldTypeDescription
namerequiredstring—
descriptionstring | null—
message_typerequiredenumtransactional | marketing—
canonical_purposestring | null—
frequency_disclosurestring | null—
opt_in_typestring | null—
opt_in_workflowstring | null—
opt_in_confirmationstring | null—
help_messagestring | null—
stop_messagestring | null—
terms_urlstring | null—
privacy_urlstring | null—
monthly_volumestring | null—
sample_messagesrequiredstring[]—
embedded_linksrequiredboolean—
embedded_link_samplestring | null—
embedded_phonesrequiredboolean—
age_gatedrequiredboolean—
provider_overridesobject | null—
recipe_idrequiredstring | null—
consent_setup_idstring | nullA consent setup (`cset_…`) this workspace has.
objectrequiredstring—
idrequiredstring—
recipe_versionrequiredinteger | null—
revisionrequiredintegerMoves on a material change; registrations keep the revision they copied.
readinessrequiredobjectWhether the program has what a registration needs; `missing` names the fields still to fill (the wizard's own check).
archived_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404422

Update a messaging program

PATCH/api/v1/sms/messaging-programs/{id}

PATCH /sms/messaging-programs/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/sms/messaging-programs/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "name": "Example",
  "description": "string",
  "message_type": "transactional",
  "canonical_purpose": "string",
  "frequency_disclosure": "string",
  "opt_in_type": "string",
  "opt_in_workflow": "string",
  "opt_in_confirmation": "string",
  "help_message": "string",
  "stop_message": "string",
  "terms_url": "https://example.com",
  "privacy_url": "https://example.com",
  "monthly_volume": "string",
  "sample_messages": [
    "string"
  ],
  "embedded_links": false,
  "embedded_link_sample": "string",
  "embedded_phones": false,
  "age_gated": false,
  "provider_overrides": {
    "toll_free": {
      "use_case_category": "string"
    },
    "ten_dlc": {
      "use_case": "string",
      "sub_use_cases": [
        "string"
      ]
    }
  },
  "recipe_id": "recipe_123",
  "consent_setup_id": "consent_setup_123",
  "object": "sms_messaging_program",
  "id": "id_123",
  "recipe_version": 0,
  "revision": 0,
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ]
  },
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Edit a program: only the fields sent change, null clears one, and the result must still pass the carriers' rules. revision moves on a material change; registrations keep the copy they made. An archived program is a 409: duplicate it to keep editing. Requires the sms:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body21 fields
FieldTypeDescription
namestring—
descriptionstring | null—
message_typeenumtransactional | marketing—
canonical_purposestring | null—
frequency_disclosurestring | null—
opt_in_typestring | null—
opt_in_workflowstring | null—
opt_in_confirmationstring | null—
help_messagestring | null—
stop_messagestring | null—
terms_urlstring | null—
privacy_urlstring | null—
monthly_volumestring | null—
sample_messagesstring[]—
embedded_linksboolean—
embedded_link_samplestring | null—
embedded_phonesboolean—
age_gatedboolean—
provider_overridesobject | null—
recipe_idenumACCOUNT_NOTIFICATIONS | SECURITY_ALERTS | ONE_TIME_PASSCODES | ORDER_UPDATES | APPOINTMENT_REMINDERS | CUSTOMER_SUPPORT | MARKETING_PROMOTIONS | OTHER_CUSTOMThe compliance recipe the program follows; its version is the recipe's current one. Left out, it's derived from `canonical_purpose`.
consent_setup_idstring | nullA consent setup (`cset_…`) this workspace has.
Response · 200 fields29 fields
FieldTypeDescription
namerequiredstring—
descriptionstring | null—
message_typerequiredenumtransactional | marketing—
canonical_purposestring | null—
frequency_disclosurestring | null—
opt_in_typestring | null—
opt_in_workflowstring | null—
opt_in_confirmationstring | null—
help_messagestring | null—
stop_messagestring | null—
terms_urlstring | null—
privacy_urlstring | null—
monthly_volumestring | null—
sample_messagesrequiredstring[]—
embedded_linksrequiredboolean—
embedded_link_samplestring | null—
embedded_phonesrequiredboolean—
age_gatedrequiredboolean—
provider_overridesobject | null—
recipe_idrequiredstring | null—
consent_setup_idstring | nullA consent setup (`cset_…`) this workspace has.
objectrequiredstring—
idrequiredstring—
recipe_versionrequiredinteger | null—
revisionrequiredintegerMoves on a material change; registrations keep the revision they copied.
readinessrequiredobjectWhether the program has what a registration needs; `missing` names the fields still to fill (the wizard's own check).
archived_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200400401403404409422

Archive a messaging program

DELETE/api/v1/sms/messaging-programs/{id}

DELETE /sms/messaging-programs/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/sms/messaging-programs/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Archive a program. Registrations that copied it keep their copy; Duplicate a messaging program to use it again. Requires the sms:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404422

Duplicate a messaging program

POST/api/v1/sms/messaging-programs/{id}/duplicate

POST /sms/messaging-programs/{id}/duplicate
curl -X POST 'https://www.unitpost.com/api/v1/sms/messaging-programs/123/duplicate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 201
{
  "name": "Example",
  "description": "string",
  "message_type": "transactional",
  "canonical_purpose": "string",
  "frequency_disclosure": "string",
  "opt_in_type": "string",
  "opt_in_workflow": "string",
  "opt_in_confirmation": "string",
  "help_message": "string",
  "stop_message": "string",
  "terms_url": "https://example.com",
  "privacy_url": "https://example.com",
  "monthly_volume": "string",
  "sample_messages": [
    "string"
  ],
  "embedded_links": false,
  "embedded_link_sample": "string",
  "embedded_phones": false,
  "age_gated": false,
  "provider_overrides": {
    "toll_free": {
      "use_case_category": "string"
    },
    "ten_dlc": {
      "use_case": "string",
      "sub_use_cases": [
        "string"
      ]
    }
  },
  "recipe_id": "recipe_123",
  "consent_setup_id": "consent_setup_123",
  "object": "sms_messaging_program",
  "id": "id_123",
  "recipe_version": 0,
  "revision": 0,
  "readiness": {
    "ready": false,
    "missing": [
      "string"
    ]
  },
  "archived_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Copy a program (an archived one too) into a new editable one named "… (copy)" at revision 1, its consent setup and recipe included. Takes no body. Pass an Idempotency-Key so a retry returns the same copy. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Response · 201 fields29 fields
FieldTypeDescription
namerequiredstring—
descriptionstring | null—
message_typerequiredenumtransactional | marketing—
canonical_purposestring | null—
frequency_disclosurestring | null—
opt_in_typestring | null—
opt_in_workflowstring | null—
opt_in_confirmationstring | null—
help_messagestring | null—
stop_messagestring | null—
terms_urlstring | null—
privacy_urlstring | null—
monthly_volumestring | null—
sample_messagesrequiredstring[]—
embedded_linksrequiredboolean—
embedded_link_samplestring | null—
embedded_phonesrequiredboolean—
age_gatedrequiredboolean—
provider_overridesobject | null—
recipe_idrequiredstring | null—
consent_setup_idstring | nullA consent setup (`cset_…`) this workspace has.
objectrequiredstring—
idrequiredstring—
recipe_versionrequiredinteger | null—
revisionrequiredintegerMoves on a material change; registrations keep the revision they copied.
readinessrequiredobjectWhether the program has what a registration needs; `missing` names the fields still to fill (the wizard's own check).
archived_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

SMS test numbers

The numbers a template's test text may go to besides the simulator. Adding and verifying one happens in the dashboard (a code is texted to the phone).

List SMS test numbers

GET/api/v1/sms/test-destinations

GET /sms/test-destinations
curl -X GET 'https://www.unitpost.com/api/v1/sms/test-destinations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_test_destination",
      "id": "id_123",
      "phone_number": "string",
      "status": "queued",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The numbers your workspace may text a template's test to besides the simulator: pending until the code texted to it is entered, then verified. Adding and verifying one happens in the dashboard (Phone numbers → Testing): it proves the phone is the person's. Requires the sms:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
phone_numberrequiredstring—
statusrequiredstring`pending` until the code texted to it is entered in the dashboard, then `verified`.
created_atrequiredstring—
200401403404422

Remove an SMS test number

DELETE/api/v1/sms/test-destinations/{id}

DELETE /sms/test-destinations/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/sms/test-destinations/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Remove a test number; template tests can no longer text it. Requires the sms:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404422429502

SMS registrations

Carrier registrations and their review state. Submitting a 10DLC one is an SMS quote, then its confirm.

List carrier registrations

GET/api/v1/sms/registrations

GET /sms/registrations
curl -X GET 'https://www.unitpost.com/api/v1/sms/registrations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_registration",
      "id": "id_123",
      "type": "string",
      "brand_id": "brand_123",
      "status": "queued",
      "requires_action": false,
      "feedback": [
        {}
      ],
      "use_case": "string",
      "message_type": "string",
      "parent_registration_id": "parent_registration_123",
      "auto_provision_number": false,
      "sender": {
        "id": "id_123",
        "status": "queued",
        "phone_number": "string"
      },
      "setup_state": "string",
      "number_withheld_reason": "string",
      "archived_at": "2026-01-01T00:00:00.000Z",
      "submitted_at": "2026-01-01T00:00:00.000Z",
      "completed_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Your carrier registrations (10DLC brand and campaign, toll-free) with their review state and the carrier's feedback; a 10DLC campaign also carries the number it backs and one setup state. Submitting or resubmitting a 10DLC brand is an SMS quote, then its confirm; a 10DLC campaign is resubmitted with POST /sms/registrations/{id}/resubmit and a toll-free verification with POST /sms/numbers/{id}/resubmit (both free); a 10DLC setup with no number is taken down with POST /sms/registrations/{id}/remove and an approved brand registration is replaced with POST /sms/registrations/{id}/replace. Requires the sms:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields18 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
typerequiredstring`us_ten_dlc_brand`, `us_ten_dlc_campaign`, or a toll-free verification.
brand_idrequiredstring | null—
statusrequiredstringThe carrier review state: `draft`, `submitted`, `reviewing`, `requires_updates`, `complete`, `closed`, …
requires_actionrequiredbooleanThe customer must act (the carrier asked for changes).
feedbackrequiredobject[] | nullThe carrier's reasons when it asks for changes or closes it (`reason`, `description`, `field_path`, `link`).
use_caserequiredstring | null—
message_typerequiredstring | null—
parent_registration_idrequiredstring | null—
auto_provision_numberrequiredboolean | null10DLC campaigns: a number is leased when carriers approve.
senderrequiredobject | null10DLC campaigns: the number it backs, once one exists.
setup_staterequiredstring | null10DLC campaigns: one customer-facing state over the campaign and its number.
number_withheld_reasonrequiredstring | nullWhy an approved campaign's number isn't being leased (e.g. the plan has no carrier resources).
archived_atrequiredstring | null—
submitted_atrequiredstring | null—
completed_atrequiredstring | null—
created_atrequiredstring—
200401403404422

Resubmit a 10DLC campaign

POST/api/v1/sms/registrations/{id}/resubmit

POST /sms/registrations/{id}/resubmit
curl -X POST 'https://www.unitpost.com/api/v1/sms/registrations/123/resubmit' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_registration_resubmission",
  "registration_id": "registration_123",
  "status": "queued",
  "resubmitted": true
}

Resubmit a 10DLC campaign carriers sent back (requires_updates, requires_authentication), or whose first submit never reached them, from a messaging program: fix what carriers flagged there first (feedback on List carrier registrations). Free: the same registration and committed fee; the fee tier can't change. A new opt_in_screenshot_file_id replaces the screenshot on file. An identical resubmission is refused (registration_unchanged) unless acknowledge_unchanged. Takes an Idempotency-Key. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body3 fields
FieldTypeDescription
messaging_program_idrequiredstringThe messaging program (`prog_…`) holding the corrected use case: fix what carriers flagged there first (PATCH /sms/messaging-programs/{id}), then resubmit from it. Its fee tier must match the campaign's (a low-volume campaign stays low-volume).
opt_in_screenshot_file_idstringA new opt-in screenshot (POST /files, purpose `sms_opt_in_evidence`). Without one, the screenshot carriers already have is sent again.
acknowledge_unchangedbooleanResubmit although nothing changed since carriers sent it back, because the cause was fixed outside Unitpost (the privacy page now loads). Without it an identical resubmission is refused (`registration_unchanged`).
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
registration_idrequiredstring—
statusrequiredstring | nullThe registration's state after the resubmission (`submitted`, `reviewing`, …); follow it on GET /sms/registrations.
resubmittedrequiredboolean—
200400401403404409422429502

Retry a campaign's number

POST/api/v1/sms/registrations/{id}/number

POST /sms/registrations/{id}/number
curl -X POST 'https://www.unitpost.com/api/v1/sms/registrations/123/number' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_number_request",
  "registration_id": "registration_123",
  "number_id": "number_123",
  "created": false,
  "retried": false
}

Bring back the failed local number of an approved 10DLC campaign whose monthly fee is already committed: free, nothing new is bought. A number nothing pays for yet is a purchase: 409 quote_required (Create an SMS purchase quote, product ten_dlc_number). A campaign whose number is live answers it (created: false). Takes an Idempotency-Key. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredstring—
registration_idrequiredstringThe 10DLC campaign (`sreg_…`).
number_idrequiredstringThe number (`snum_…`): read its state on GET /sms/numbers. It leases within minutes.
createdrequiredbooleanFalse when the campaign's number was already live: nothing was requested.
retriedrequiredbooleanA failed number was brought back (the same row, the same committed fee).
200201400401403404409422429502

Retrieve a carrier registration

GET/api/v1/sms/registrations/{id}

GET /sms/registrations/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/registrations/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_registration",
  "id": "id_123",
  "type": "string",
  "brand_id": "brand_123",
  "status": "queued",
  "requires_action": false,
  "feedback": [
    {}
  ],
  "use_case": "string",
  "message_type": "string",
  "parent_registration_id": "parent_registration_123",
  "auto_provision_number": false,
  "sender": {
    "id": "id_123",
    "status": "queued",
    "phone_number": "string"
  },
  "setup_state": "string",
  "number_withheld_reason": "string",
  "archived_at": "2026-01-01T00:00:00.000Z",
  "submitted_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}

One carrier registration (sreg_…), read as List carrier registrations reads it. Read a resubmit, a removal or a replacement back with it. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields18 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
typerequiredstring`us_ten_dlc_brand`, `us_ten_dlc_campaign`, or a toll-free verification.
brand_idrequiredstring | null—
statusrequiredstringThe carrier review state: `draft`, `submitted`, `reviewing`, `requires_updates`, `complete`, `closed`, …
requires_actionrequiredbooleanThe customer must act (the carrier asked for changes).
feedbackrequiredobject[] | nullThe carrier's reasons when it asks for changes or closes it (`reason`, `description`, `field_path`, `link`).
use_caserequiredstring | null—
message_typerequiredstring | null—
parent_registration_idrequiredstring | null—
auto_provision_numberrequiredboolean | null10DLC campaigns: a number is leased when carriers approve.
senderrequiredobject | null10DLC campaigns: the number it backs, once one exists.
setup_staterequiredstring | null10DLC campaigns: one customer-facing state over the campaign and its number.
number_withheld_reasonrequiredstring | nullWhy an approved campaign's number isn't being leased (e.g. the plan has no carrier resources).
archived_atrequiredstring | null—
submitted_atrequiredstring | null—
completed_atrequiredstring | null—
created_atrequiredstring—
200401403404422

Remove a 10DLC setup

POST/api/v1/sms/registrations/{id}/remove

POST /sms/registrations/{id}/remove
curl -X POST 'https://www.unitpost.com/api/v1/sms/registrations/123/remove' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_registration",
  "id": "id_123",
  "type": "string",
  "brand_id": "brand_123",
  "status": "queued",
  "requires_action": false,
  "feedback": [
    {}
  ],
  "use_case": "string",
  "message_type": "string",
  "parent_registration_id": "parent_registration_123",
  "auto_provision_number": false,
  "sender": {
    "id": "id_123",
    "status": "queued",
    "phone_number": "string"
  },
  "setup_state": "string",
  "number_withheld_reason": "string",
  "archived_at": "2026-01-01T00:00:00.000Z",
  "submitted_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Take down a 10DLC campaign registration (us_ten_dlc_campaign) that has no active number: the carrier registration is deleted, the campaign's monthly fee ends (no proration) and the registration reads archived_at from then on. A campaign with a live number is refused (resource_in_use): releasing the number with Release an SMS number takes the campaign with it, so there's nothing to remove after (while that release is in flight: sms_release_pending with Retry-After). One under carrier review waits for the review (conflict). Works on any plan. Takes an Idempotency-Key. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Response · 200 fields18 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
typerequiredstring`us_ten_dlc_brand`, `us_ten_dlc_campaign`, or a toll-free verification.
brand_idrequiredstring | null—
statusrequiredstringThe carrier review state: `draft`, `submitted`, `reviewing`, `requires_updates`, `complete`, `closed`, …
requires_actionrequiredbooleanThe customer must act (the carrier asked for changes).
feedbackrequiredobject[] | nullThe carrier's reasons when it asks for changes or closes it (`reason`, `description`, `field_path`, `link`).
use_caserequiredstring | null—
message_typerequiredstring | null—
parent_registration_idrequiredstring | null—
auto_provision_numberrequiredboolean | null10DLC campaigns: a number is leased when carriers approve.
senderrequiredobject | null10DLC campaigns: the number it backs, once one exists.
setup_staterequiredstring | null10DLC campaigns: one customer-facing state over the campaign and its number.
number_withheld_reasonrequiredstring | nullWhy an approved campaign's number isn't being leased (e.g. the plan has no carrier resources).
archived_atrequiredstring | null—
submitted_atrequiredstring | null—
completed_atrequiredstring | null—
created_atrequiredstring—
200400401403404409422429502

Replace a 10DLC brand registration

POST/api/v1/sms/registrations/{id}/replace

POST /sms/registrations/{id}/replace
curl -X POST 'https://www.unitpost.com/api/v1/sms/registrations/123/replace' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_registration",
  "id": "id_123",
  "type": "string",
  "brand_id": "brand_123",
  "status": "queued",
  "requires_action": false,
  "feedback": [
    {}
  ],
  "use_case": "string",
  "message_type": "string",
  "parent_registration_id": "parent_registration_123",
  "auto_provision_number": false,
  "sender": {
    "id": "id_123",
    "status": "queued",
    "phone_number": "string"
  },
  "setup_state": "string",
  "number_withheld_reason": "string",
  "archived_at": "2026-01-01T00:00:00.000Z",
  "submitted_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z"
}

Archive an APPROVED 10DLC brand registration (us_ten_dlc_brand) so the brand can be registered again (corrected legal details, a new owner of the EIN): the brand unlocks for Update an SMS brand, and a new registration is a quote and its confirm (product ten_dlc_brand_registration). Nothing changes at the carrier and nothing is charged here. Refused while any number on the brand isn't released or any of its 10DLC setups isn't removed (resource_in_use; each one in error.details[], its public id first). When all that's left is a release in flight: sms_release_pending with Retry-After. Takes an Idempotency-Key. Requires the sms:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Response · 200 fields18 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
typerequiredstring`us_ten_dlc_brand`, `us_ten_dlc_campaign`, or a toll-free verification.
brand_idrequiredstring | null—
statusrequiredstringThe carrier review state: `draft`, `submitted`, `reviewing`, `requires_updates`, `complete`, `closed`, …
requires_actionrequiredbooleanThe customer must act (the carrier asked for changes).
feedbackrequiredobject[] | nullThe carrier's reasons when it asks for changes or closes it (`reason`, `description`, `field_path`, `link`).
use_caserequiredstring | null—
message_typerequiredstring | null—
parent_registration_idrequiredstring | null—
auto_provision_numberrequiredboolean | null10DLC campaigns: a number is leased when carriers approve.
senderrequiredobject | null10DLC campaigns: the number it backs, once one exists.
setup_staterequiredstring | null10DLC campaigns: one customer-facing state over the campaign and its number.
number_withheld_reasonrequiredstring | nullWhy an approved campaign's number isn't being leased (e.g. the plan has no carrier resources).
archived_atrequiredstring | null—
submitted_atrequiredstring | null—
completed_atrequiredstring | null—
created_atrequiredstring—
200400401403404409422

SMS billing

What your workspace pays for SMS every month. Buying a carrier resource is an SMS quote, then its confirm.

List recurring SMS charges

GET/api/v1/sms/billing/resources

GET /sms/billing/resources
curl -X GET 'https://www.unitpost.com/api/v1/sms/billing/resources' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_billable_resource",
      "id": "id_123",
      "label": "string",
      "resource_type": "string",
      "phone_number": "string",
      "country": "string",
      "monthly_price_cents": 0,
      "status": "queued",
      "billing_started_at": "2026-01-01T00:00:00.000Z",
      "next_charge_at": "2026-01-01T00:00:00.000Z",
      "grace_until": "string",
      "billable_to_customer": false,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

What your workspace pays for SMS every month: each number and 10DLC campaign, its monthly price, status, next charge and, for a past-due number, the date it is released. Buying a carrier resource is an SMS quote, then its confirm. Requires the sms:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
labelrequiredstringWhat the charge is for (a local number, a 10DLC campaign, …).
resource_typerequiredstring—
phone_numberrequiredstring | nullFor a number, which one.
countryrequiredstring | null—
monthly_price_centsrequiredinteger—
statusrequiredstring—
billing_started_atrequiredstring | null—
next_charge_atrequiredstring | null—
grace_untilrequiredstring | nullA past-due number is released after this.
billable_to_customerrequiredboolean—
created_atrequiredstring—
200401403404422

SMS quotes

Buy carrier resources by API: quote (sms:manage, nothing charged), show the person the price, then confirm with the quote's single-use token and an Idempotency-Key (sms:purchase, which no key preset includes). API purchases count against a monthly cap the workspace owner sets in the dashboard; with none set they are refused. A toll-free number takes its opt-in evidence as a file (opt_in_evidence_file_id). Releasing a number stays in the dashboard.

Create an SMS purchase quote

POST/api/v1/sms/quotes

POST /sms/quotes
curl -X POST 'https://www.unitpost.com/api/v1/sms/quotes' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "sms_quote",
  "id": "id_123",
  "product": "ten_dlc_brand_registration",
  "status": "open",
  "label": "string",
  "brand_id": "brand_123",
  "registration_id": "registration_123",
  "messaging_program_id": "messaging_program_123",
  "country": "string",
  "due_now_cents": 0,
  "monthly_cents": 0,
  "currency": "usd",
  "line_items": [
    {
      "fee_code": "string",
      "label": "string",
      "amount_cents": 0,
      "cadence": "one_time",
      "starts_when": "on_confirmation"
    }
  ],
  "covered_by_unitpost": false,
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "order": {
    "registration_id": "registration_123",
    "number_id": "number_123",
    "status": "queued"
  },
  "confirm_token": "string"
}

Price a carrier purchase and bind exactly what it buys: a 10DLC brand registration (or the paid resubmission of one carriers sent back), brand vetting, a 10DLC campaign registered from a messaging program with its local number, the number of an approved campaign that has none, or a local number that needs no registration (Canada). Nothing is charged or submitted. The answer names the product, due_now_cents (charged at the confirm), monthly_cents (from when the number leases or carriers approve the campaign, then monthly), the line items and expires_at (10 minutes), and carries a single-use confirm_token, shown once. Show the person the price, then Confirm an SMS purchase quote. A toll-free number is composed from the brand and a messaging program, with its opt-in evidence as a file (opt_in_evidence_file_id, made with Create a file). Something already registered or under review, a number the plan can't hold, a failing card or a fee the plan can't fit are refused here, before a price is shown. Requires the sms:manage capability.

Request body12 fields
FieldTypeDescription
productrequiredenumten_dlc_brand_registration | ten_dlc_brand_vetting | ten_dlc_campaign | ten_dlc_number | long_code_number | toll_free_numberWhat to buy. `ten_dlc_brand_registration` registers a brand with US carriers (or resubmits one they sent back; the fee is the resubmission's). `ten_dlc_brand_vetting` vets an approved brand for higher throughput. `ten_dlc_campaign` registers a 10DLC campaign from a messaging program, with its local number, which leases once carriers approve it. `ten_dlc_number` orders the number of an approved campaign that has none (a failed number whose fee is already committed is retried for free: POST /sms/registrations/{id}/number). `long_code_number` orders a local number that needs no registration (`country: "CA"`). `toll_free_number` orders a US toll-free number and files its carrier verification from the brand and a messaging program, with the opt-in evidence as a file (`opt_in_evidence_file_id`).
brand_idstringThe SMS brand (`sbrand_…`).
registration_idstring`ten_dlc_number`: the approved 10DLC campaign registration (`sreg_…`).
messaging_program_idstring`ten_dlc_campaign`: the messaging program (`prog_…`) the campaign is registered from.
countrystring`long_code_number`: the two-letter country (`CA`).
display_namestring`long_code_number`: the number's name in the dashboard.
brand_verification_emailstring`ten_dlc_brand_registration`: who at the company follows the registry's email link, on the brand website's domain. Required for a public company, or when carriers ask for it; else the brand's saved one.
acknowledge_unchangedboolean`ten_dlc_brand_registration`, a resubmission: send it anyway although nothing carriers flagged changed, because the cause was fixed outside Unitpost (the website now loads, the registry was updated). Without it, an identical resubmission is refused (`registration_unchanged`, nothing charged).
opt_in_screenshot_file_idstring`ten_dlc_campaign`: a screenshot of the opt-in (POST /files, purpose `sms_opt_in_evidence`: PNG up to 400 KB). Carriers require one for verbal or printed opt-in, or when the opt-in workflow links to no public page.
opt_in_evidence_file_idstring`toll_free_number`: the opt-in evidence carriers review (POST /files, purpose `sms_opt_in_evidence`: a PNG up to 400 KB of the form, page or flow where people agree to receive these texts).
business_registration_document_file_idstring`toll_free_number`: an IRS letter (CP 575, 147C or SS-4) or registry extract showing the legal name and company ID (POST /files, purpose `sms_document`, up to 2 MB). Required when the brand is a government agency.
consent_source_urlstring`toll_free_number`: the public https page where people opt in (your form or checkout). Goes into the opt-in description carriers read.
Response · 201 fields19 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe quote (`squote_…`).
productrequiredenumten_dlc_brand_registration | ten_dlc_brand_vetting | ten_dlc_campaign | ten_dlc_number | long_code_number | toll_free_number—
statusrequiredenumopen | expired | confirming | ordered | pending | failed`open` until confirmed or `expires_at`; `ordered` once placed; `pending` while the outcome is unknown (the carrier didn't answer: a fee due now is held, monthly fees are committed, and it settles to `ordered` or `failed` from the billing ledger, so read it again; don't buy the same thing meanwhile); `failed` when the confirm bought nothing (nothing was charged; quote again).
labelrequiredstringWhat is bought, as the dashboard names it.
brand_idrequiredstring | null—
registration_idrequiredstring | nullThe registration the order is for (a brand registration, or the campaign whose number it is).
messaging_program_idrequiredstring | null—
countryrequiredstring | null—
due_now_centsrequiredintegerCharged at the confirm, from the plan's allowance (one-time fees).
monthly_centsrequiredintegerCharged when the number leases or carriers approve the campaign, then every month.
currencyrequiredstring—
line_itemsrequiredobject[]—
covered_by_unitpostrequiredbooleanThis workspace's carrier fees are covered by Unitpost: nothing is charged.
expires_atrequiredstringConfirm before this (quotes last 10 minutes).
created_atrequiredstring—
confirmed_atrequiredstring | null—
orderrequiredobject | nullWhat the confirmed order made; null until then.
confirm_tokenstringOnly in the create response, once: pass it to the confirm. Stored only as a hash; a lost token means a new quote.
201400401402403404409422429

Retrieve an SMS purchase quote

GET/api/v1/sms/quotes/{id}

GET /sms/quotes/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/quotes/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_quote",
  "id": "id_123",
  "product": "ten_dlc_brand_registration",
  "status": "open",
  "label": "string",
  "brand_id": "brand_123",
  "registration_id": "registration_123",
  "messaging_program_id": "messaging_program_123",
  "country": "string",
  "due_now_cents": 0,
  "monthly_cents": 0,
  "currency": "usd",
  "line_items": [
    {
      "fee_code": "string",
      "label": "string",
      "amount_cents": 0,
      "cadence": "one_time",
      "starts_when": "on_confirmation"
    }
  ],
  "covered_by_unitpost": false,
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "order": {
    "registration_id": "registration_123",
    "number_id": "number_123",
    "status": "queued"
  },
  "confirm_token": "string"
}

A quote's price and state: open until confirmed or expired, ordered with what the order made (order.registration_id or order.number_id), pending while the outcome is unknown (the carrier didn't answer: a fee due now is held, monthly fees are committed), or failed when the confirm bought nothing (nothing was charged). A pending quote settles from the billing ledger when it is read: ordered once the fee is captured or the number or campaign goes live, failed once the fee is refunded or the commitments are released. An ordered number or campaign whose commitments are released before it ever goes live reads failed too and stops counting against the cap. Never the confirm token. Requires the sms:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields19 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe quote (`squote_…`).
productrequiredenumten_dlc_brand_registration | ten_dlc_brand_vetting | ten_dlc_campaign | ten_dlc_number | long_code_number | toll_free_number—
statusrequiredenumopen | expired | confirming | ordered | pending | failed`open` until confirmed or `expires_at`; `ordered` once placed; `pending` while the outcome is unknown (the carrier didn't answer: a fee due now is held, monthly fees are committed, and it settles to `ordered` or `failed` from the billing ledger, so read it again; don't buy the same thing meanwhile); `failed` when the confirm bought nothing (nothing was charged; quote again).
labelrequiredstringWhat is bought, as the dashboard names it.
brand_idrequiredstring | null—
registration_idrequiredstring | nullThe registration the order is for (a brand registration, or the campaign whose number it is).
messaging_program_idrequiredstring | null—
countryrequiredstring | null—
due_now_centsrequiredintegerCharged at the confirm, from the plan's allowance (one-time fees).
monthly_centsrequiredintegerCharged when the number leases or carriers approve the campaign, then every month.
currencyrequiredstring—
line_itemsrequiredobject[]—
covered_by_unitpostrequiredbooleanThis workspace's carrier fees are covered by Unitpost: nothing is charged.
expires_atrequiredstringConfirm before this (quotes last 10 minutes).
created_atrequiredstring—
confirmed_atrequiredstring | null—
orderrequiredobject | nullWhat the confirmed order made; null until then.
confirm_tokenstringOnly in the create response, once: pass it to the confirm. Stored only as a hash; a lost token means a new quote.
200401403404422

Confirm an SMS purchase quote

POST/api/v1/sms/quotes/{id}/confirm

POST /sms/quotes/{id}/confirm
curl -X POST 'https://www.unitpost.com/api/v1/sms/quotes/123/confirm' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_quote",
  "id": "id_123",
  "product": "ten_dlc_brand_registration",
  "status": "open",
  "label": "string",
  "brand_id": "brand_123",
  "registration_id": "registration_123",
  "messaging_program_id": "messaging_program_123",
  "country": "string",
  "due_now_cents": 0,
  "monthly_cents": 0,
  "currency": "usd",
  "line_items": [
    {
      "fee_code": "string",
      "label": "string",
      "amount_cents": 0,
      "cadence": "one_time",
      "starts_when": "on_confirmation"
    }
  ],
  "covered_by_unitpost": false,
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "order": {
    "registration_id": "registration_123",
    "number_id": "number_123",
    "status": "queued"
  },
  "confirm_token": "string"
}

Buy what the quote binds, with its single-use confirm_token. It charges the workspace: confirm only after the person agreed to the quoted price. Requires an Idempotency-Key: a retry with the same key answers what the first call answered and never charges twice. The order runs exactly as in the dashboard: the plan's purchase rules, the one-time fee taken from the plan's allowance before carriers are called and refunded if they refuse the submission, the monthly fee from when the number leases or carriers approve the campaign. Every API purchase counts against the workspace's monthly API spend cap (the fee due now plus the first month, per UTC month): read it with GET /spend-caps; the workspace owner sets it in the dashboard or with PATCH /spend-caps (spend_caps:write), at most the platform maximum ($1,000 a month by default). A workspace that starts a paid plan on its own card starts with a $75 cap when it has none, unless a key or app of it already holds sms:purchase (a workspace its organization pays for follows the organization Owner's rules instead; a key still needs sms:purchase to buy). With no cap set, API purchases are refused (api_spend_cap_not_set), and one over it is api_spend_cap_exceeded; the dashboard buys past it. The owner gets an email per purchase, and the activity log names the key. Refusals charge nothing: a changed price (price_changed), an expired quote (quote_expired), a brand or messaging program edited since (quote_stale), a quote already used (quote_already_used), an order for the same purchase still in flight (conflict, naming its quote). These refusals are answered before the shared hourly limits are spent. A confirm that recorded nothing leaves the quote open (and frees its Idempotency-Key); one that reached carriers spends it: failed when carriers refused it (quote again), pending when their answer is unknown (follow the quote; don't buy the same thing meanwhile). Requires the sms:purchase capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keyrequiredstring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
confirm_tokenrequiredstringThe quote's confirm token (`sqct_…`), from its create response. Single use.
Response · 200 fields19 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe quote (`squote_…`).
productrequiredenumten_dlc_brand_registration | ten_dlc_brand_vetting | ten_dlc_campaign | ten_dlc_number | long_code_number | toll_free_number—
statusrequiredenumopen | expired | confirming | ordered | pending | failed`open` until confirmed or `expires_at`; `ordered` once placed; `pending` while the outcome is unknown (the carrier didn't answer: a fee due now is held, monthly fees are committed, and it settles to `ordered` or `failed` from the billing ledger, so read it again; don't buy the same thing meanwhile); `failed` when the confirm bought nothing (nothing was charged; quote again).
labelrequiredstringWhat is bought, as the dashboard names it.
brand_idrequiredstring | null—
registration_idrequiredstring | nullThe registration the order is for (a brand registration, or the campaign whose number it is).
messaging_program_idrequiredstring | null—
countryrequiredstring | null—
due_now_centsrequiredintegerCharged at the confirm, from the plan's allowance (one-time fees).
monthly_centsrequiredintegerCharged when the number leases or carriers approve the campaign, then every month.
currencyrequiredstring—
line_itemsrequiredobject[]—
covered_by_unitpostrequiredbooleanThis workspace's carrier fees are covered by Unitpost: nothing is charged.
expires_atrequiredstringConfirm before this (quotes last 10 minutes).
created_atrequiredstring—
confirmed_atrequiredstring | null—
orderrequiredobject | nullWhat the confirmed order made; null until then.
confirm_tokenstringOnly in the create response, once: pass it to the confirm. Stored only as a hash; a lost token means a new quote.
200400401402403404409422429500502

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. Paid plans only, like every SMS send.

List SMS campaigns

GET/api/v1/sms/campaigns

GET /sms/campaigns
curl -X GET 'https://www.unitpost.com/api/v1/sms/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_campaign",
      "id": "id_123",
      "name": "Example",
      "status": "draft",
      "type": "marketing",
      "template_id": "template_123",
      "segment_id": "segment_123",
      "sender_id": "sender_123",
      "topic_id": "topic_123",
      "routing": "automatic",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "hold": {
        "reason": "scheduled",
        "until": "string"
      },
      "pause_reason": {
        "code": "user",
        "message": "string",
        "paused_at": "2026-01-01T00:00:00.000Z"
      },
      "projected_recipients": {
        "total": 1,
        "reachable": 0,
        "skipped": 0
      },
      "recipient_count": 1,
      "variable_fallbacks": {},
      "excluded_contact_ids": [
        "string"
      ],
      "started_at": "2026-01-01T00:00:00.000Z",
      "completed_at": "2026-01-01T00:00:00.000Z",
      "canceled_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

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.

Parameters6 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
archivedboolean · queryWhen true, list only archived SMS campaigns instead of active ones.
topic_idstring · queryOnly campaigns scoped to this topic. An id from another workspace or channel matches nothing.
segment_idstring · queryOnly campaigns aimed at this segment (`seg_…`).
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404422

Create an SMS campaign

POST/api/v1/sms/campaigns

POST /sms/campaigns
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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, then send it with Send an SMS campaign. Requires the campaigns:write capability.

Request body8 fields
FieldTypeDescription
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
sender_idstring | null—
topic_idstring | null—
excluded_contact_idsstring[]—
variable_fallbacksobject—
scheduled_atstring | null—
Response · 201 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
201401403404422

Retrieve an SMS campaign

GET/api/v1/sms/campaigns/{id}

GET /sms/campaigns/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404

Update an SMS campaign

PATCH/api/v1/sms/campaigns/{id}

PATCH /sms/campaigns/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body9 fields
FieldTypeDescription
archivedboolean—
namestring—
template_idstring—
segment_idstring—
sender_idstring | null—
topic_idstring | null—
excluded_contact_idsstring[]—
variable_fallbacksobject—
scheduled_atstring | null—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Delete an SMS campaign

DELETE/api/v1/sms/campaigns/{id}

DELETE /sms/campaigns/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

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. A scheduled, sending or paused campaign returns 409: cancel it first with Cancel an SMS campaign. Requires the campaigns:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404409

Send an SMS campaign

POST/api/v1/sms/campaigns/{id}/send

POST /sms/campaigns/{id}/send
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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; right after an Unschedule it answers 409 send_time_required instead), pass null to send now, or a time (ISO 8601 with Z or an offset) to schedule it. A misnamed time field (scheduledAt, send_at, …) is a 422 and nothing is sent; other fields are ignored. API sends run the same checks as the dashboard: plan, schedule window, carrier registration and content rules, topic, and sending limits. A plan without SMS returns 403 limit_reached, with feature_not_in_plan on smsChannel in error.details[]. Any other check 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.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
scheduled_atstring | null—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200400401403404409422429

Cancel an SMS campaign

POST/api/v1/sms/campaigns/{id}/cancel

POST /sms/campaigns/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Cancel a scheduled, sending or paused SMS campaign. Messages already handed to the carrier are not recalled. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200202401403404409422

Pause an SMS campaign

POST/api/v1/sms/campaigns/{id}/pause

POST /sms/campaigns/{id}/pause
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/pause' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Pause a scheduled or sending SMS campaign. Recipients not yet sent to wait until you resume it. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Unschedule an SMS campaign

POST/api/v1/sms/campaigns/{id}/unschedule

POST /sms/campaigns/{id}/unschedule
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/unschedule' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Move a scheduled SMS campaign (or one held for quiet hours, or paused before it started) back to draft, same id, so you can edit it. The saved send time is cleared; nothing was charged, so nothing is refunded. No body; any key is a 422. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Duplicate an SMS campaign

POST/api/v1/sms/campaigns/{id}/duplicate

POST /sms/campaigns/{id}/duplicate
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/duplicate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Copy an SMS campaign into a new draft: template, segment, sender, topic, exclusions and fallbacks; never the send time or status. A source that points at a deleted template or an archived segment is a 422; readiness problems (unpublished template, sender not live) don't stop the copy, and Validate an SMS campaign reports them. Optional name for the copy; any other key is a 422. Pass an Idempotency-Key so a retry returns the same copy. Requires the campaigns:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
namestringName of the copy. Defaults to the source's name with " (copy)".
Response · 201 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

List an SMS campaign's recipients

GET/api/v1/sms/campaigns/{id}/recipients

GET /sms/campaigns/{id}/recipients
curl -X GET 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/recipients' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sms_campaign_recipient",
      "id": "id_123",
      "contact_id": "contact_123",
      "to": "customer@example.com",
      "name": "Example",
      "status": "delivered",
      "reason": "string",
      "reason_code": "string",
      "message_id": "message_123",
      "segments": 0,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "skipped_by_reason": [
    {
      "reason": "string",
      "count": 1
    }
  ]
}

How each recipient of an SMS campaign fared: the carrier's answer for a text that went out (delivered, sent, failed, …), or why none was sent (skipped, with reason_code: opted_out, no_marketing_consent, …). Newest first, cursor-paginated on id; q matches digits of the number. skipped_by_reason counts skipped recipients over the whole campaign, on the first page (null on the others). A bad limit or q, or any other query key, is a 422. Requires the campaigns:read capability.

Parameters5 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
qstring · queryDigits of the recipient's number.
Response · 200 fields11 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThis recipient row (`rcpt_…`); pass the last one as `after` for the next page.
contact_idrequiredstring | null—
torequiredstring | nullThe number in E.164.
namerequiredstring | null—
statusrequiredenumdelivered | sent | failed | suppressed | canceled | deferred | pending | skippedThe carrier's answer when a text exists, else why none was sent (`skipped`).
reasonrequiredstring | nullWhy it failed or was skipped, in plain words.
reason_coderequiredstring | nullThe SMS skip reason (`opted_out`, `no_marketing_consent`, …) when there is one.
message_idrequiredstring | nullThe text (`sms_…`); read it with `GET /sms/{id}`.
segmentsrequiredinteger | nullSegments billed.
created_atrequiredstring—
200401403404422503

Resume an SMS campaign

POST/api/v1/sms/campaigns/{id}/resume

POST /sms/campaigns/{id}/resume
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/resume' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

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, and a plan that no longer includes SMS returns 403 limit_reached. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Reschedule an SMS campaign

POST/api/v1/sms/campaigns/{id}/reschedule

POST /sms/campaigns/{id}/reschedule
curl -X POST 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/reschedule' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "sms_campaign",
  "id": "id_123",
  "name": "Example",
  "status": "draft",
  "type": "marketing",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "sender_id": "sender_123",
  "topic_id": "topic_123",
  "routing": "automatic",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "hold": {
    "reason": "scheduled",
    "until": "string"
  },
  "pause_reason": {
    "code": "user",
    "message": "string",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "recipient_count": 1,
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "started_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Move a scheduled SMS campaign to a new future scheduled_at inside your plan's scheduling window. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
scheduled_atrequiredstringISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). A time without a timezone, a bare date, or natural language is a `422`.
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
typerequiredenummarketing | transactional—
template_idrequiredstring—
segment_idrequiredstring—
sender_idrequiredstring | null—
topic_idrequiredstring | null—
routingrequiredenumautomatic | fixed | pool—
scheduled_atrequiredstring | null—
holdrequiredobject | null—
pause_reasonrequiredobject | null—
projected_recipientsrequiredobject | null—
recipient_countrequirednumber—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
started_atrequiredstring | null—
completed_atrequiredstring | null—
canceled_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Validate an SMS campaign

GET/api/v1/sms/campaigns/{id}/validate

GET /sms/campaigns/{id}/validate
curl -X GET 'https://www.unitpost.com/api/v1/sms/campaigns/cmp_123/validate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sms_campaign_validation",
  "campaign_id": "campaign_123",
  "can_send": false,
  "blockers": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "total": 1,
  "reachable": 0,
  "skipped": 0,
  "no_marketing_consent": 0,
  "quiet_hours_deferred": 0,
  "skipped_by_reason": [
    {
      "reason": "string",
      "count": 1,
      "remedy": "string"
    }
  ],
  "routing": "automatic",
  "earliest_start": {
    "at": "string",
    "reason": "quiet_hours",
    "countries": [
      "string"
    ]
  },
  "use_case_mismatch": false,
  "unresolved_variables": [
    "string"
  ],
  "variable_coverage": [
    {
      "name": "Example",
      "missing_count": 1,
      "eligible": 0,
      "missing_for_all": false,
      "has_default": false
    }
  ]
}

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; variable_coverage[] says per variable whether a variable_fallbacks default is required (missing_for_all) or only fills blanks. Rate-limited per workspace. Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredstring—
campaign_idrequiredstring—
can_sendrequiredboolean—
blockersrequiredobject[]—
totalrequirednumber—
reachablerequirednumber—
skippedrequirednumber—
no_marketing_consentrequirednumber—
quiet_hours_deferredrequirednumber—
skipped_by_reasonrequiredobject[]—
routingrequiredenumautomatic | fixed | pool—
earliest_startrequiredobject | null—
use_case_mismatchrequiredboolean—
unresolved_variablesrequiredstring[]—
variable_coverageobject[]Per template variable that some recipients lack, missing-for-all first. `missing_for_all`: no recipient has it, so a `variable_fallbacks` default is REQUIRED to send. Otherwise a default is optional and only fills the `missing_count` blanks (it never replaces a recipient's own value); or exclude those contacts. `has_default`: the campaign already sets one.
200202401403404409429

SMS topics

SMS subscription categories recipients can opt out of, independent from email topics. STOP still opts a number out of every SMS.

List SMS topics

GET/api/v1/sms/topics

GET /sms/topics
curl -X GET 'https://www.unitpost.com/api/v1/sms/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "topic",
      "id": "id_123",
      "name": "Example",
      "description": "string",
      "channel": "email",
      "default_opt_in": false,
      "subscriber_count": 1,
      "unsubscribed_count": 1,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve your SMS subscription topics, cursor-paginated. An SMS topic is a category of marketing SMS (e.g. Flash sales) recipients can opt out of while still receiving your other texts. SMS and email topics are separate: a contact's email preference never changes their SMS one, and STOP still opts a number out of every SMS. Pass ?archived=true to list archived topics instead. Create one with Create an SMS topic. Requires the topics:read capability.

Parameters4 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
archivedboolean · queryWhen true, list only archived SMS topics instead of active ones.
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401403404422503

Create an SMS topic

POST/api/v1/sms/topics

POST /sms/topics
curl -X POST 'https://www.unitpost.com/api/v1/sms/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create an SMS subscription topic. default_opt_in decides whether contacts with no explicit preference are treated as subscribed. Names are unique per channel, so an SMS topic may share a name with an email topic. Topics are a plan feature: an unentitled workspace gets 403 with limit_reached. Requires the topics:write capability.

Request body3 fields
FieldTypeDescription
namerequiredstring—
descriptionstring—
default_opt_inboolean—
Response · 201 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
201401403404409422

Retrieve an SMS topic

GET/api/v1/sms/topics/{id}

GET /sms/topics/{id}
curl -X GET 'https://www.unitpost.com/api/v1/sms/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single SMS topic by id. An email topic id returns 404 here. Change it with Update an SMS topic. Requires the topics:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401403404503

Update an SMS topic

PATCH/api/v1/sms/topics/{id}

PATCH /sms/topics/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/sms/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update an SMS topic's name, description or default_opt_in, or pass { "archived": true | false } to archive or restore it. Changing default_opt_in subscribes (true) or unsubscribes (false) every contact with no explicit choice on the topic at once (SMS marketing still needs each one's consent); Unitpost-Warning names how many. Archiving is blocked with 409 while an active SMS campaign or a live automation still uses the topic. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
namestring—
descriptionstring | null—
default_opt_inboolean—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Delete an SMS topic

DELETE/api/v1/sms/topics/{id}

DELETE /sms/topics/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/sms/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Archive an SMS topic (a soft delete: subscription records are kept so you can restore it with { "archived": false } on Update an SMS topic). Blocked with 409 while an active SMS campaign or a live automation still uses it. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404409

Opt contacts out of an SMS topic

POST/api/v1/sms/topics/{id}/opt-out

POST /sms/topics/{id}/opt-out
curl -X POST 'https://www.unitpost.com/api/v1/sms/topics/top_123/opt-out' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Opt many contacts out of this topic in one call, as a background job: the contacts you list (contact_ids or emails, up to 1,000, each a contact of this workspace) or every member of a segment (segment_id, however many; also needs segments:read). Send exactly one. Each contact is opted out as Set a contact's topic preference would: one that was subscribed gets a topic.unsubscribed webhook and an activity row naming your key; one already opted out is left as it is, with no webhook. Suppressions and other topics are untouched, and there is no bulk opt-in. Listed contacts are checked first: the first that isn't one of yours is a 404 naming it (details), and nothing starts. The answer is the job (202, Location); follow it with Retrieve a job. Pass an Idempotency-Key so a retry answers the same job instead of starting another. An email topic's id is a 404 here. Requires the topics:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body3 fields
FieldTypeDescription
contact_idsstring[]Contacts of this workspace (`con_…`), up to 1,000.
emailsstring[]Contacts of this workspace by email address, up to 1,000.
segment_idstringEvery member of this segment (`seg_…`), however many. Also needs `segments:read`.
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422429502

Search docs and guides

Search the docs and product guides.