SMS

Send an SMS message

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.

post/sms

Request

  • Base URL: https://www.unitpost.com/api/v1
  • URL: https://www.unitpost.com/api/v1/sms
  • Auth: HTTP bearer

Request body

tostring required

Recipient phone number in E.164 format, e.g. +15551234567.

fromstring

Optional 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: 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.

bodystring required

Message text. Billing is per segment (160 GSM-7 chars single-segment, 153 per segment concatenated; 70/67 for Unicode).

type'transactional' | 'marketing'

Marketing sends require the recipient's prior express consent on record and honor recipient-local quiet hours.

scheduled_atstring date-time

ISO-8601 time to send at. Omit to send immediately.

create_contactboolean

Create 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.

Response

Accepted for delivery or scheduled.

object'sms' required
idstring required
tostring required
fromstring nullable required
direction'outbound' | 'inbound' required
status'queued' | 'scheduled' | 'sending' | 'sent' | 'delivered' | 'failed' | 'suppressed' | 'canceled' | 'received' required
type'transactional' | 'marketing' required
bodystring nullable required
segmentsinteger required
countrystring nullable required
scheduled_atstring nullable required
last_errorstring nullable required

Legacy free-text error. Prefer error.code.

created_atstring required

Changes

No recorded changes to this operation across all 1 revision of this API.