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 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).
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. Itsmissinglist says what is still needed. Free. - Use case:
sms.messagingPrograms.createwith 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 withfiles.create(POST /files), from a publicurlor base64. An agent with a terminal hands over a local file with an upload session:files.createwithcontent_typeandsize_bytes, thencurl -Tthe file to theupload.urlit 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, thensms.quotes.confirm):ten_dlc_brand_registration, thenten_dlc_campaignfrom the use case with its number, or atoll_free_numberwith the opt-in screenshot asopt_in_evidence_file_id. Confirming needssms:purchaseon 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 is403 api_spend_cap_exceeded, and one with no cap403 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 gavespend_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.addBrandDocumentwith afile_id. - When carriers send something back, its
feedbacksays what (GET /sms/registrations, GET /sms/numbers). Fix the brand or the use case, then resubmit for free:sms.registrations.resubmit(a 10DLC campaign) orsms.resubmitNumber(a toll-free number). A failed number whose fee is already paid comes back withsms.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).
- SMS vs email — what is different before you send.
- Brands and Senders — the setup, in the dashboard or by API.
- SMS API — every call, on one page.