How the product fits together. API, SMTP, and agent setup live in the docs.
Getting started
What the dashboard is for, how the wallet pays for sending, and how contacts, segments, and campaigns connect. SMS is the same audience, with its own consent and sending identity.
Unitpost has two ways to send email: the API (transactional mail — receipts, password resets, one-to-one messages triggered by your app) and Campaigns (one-to-many marketing sends to an audience). SMS uses the same contacts and segments. A brand is the business carriers register before they approve a number, a sender is the number or Sender ID that can reach a country, and a marketing text needs consent on record and stays inside quiet hours. The SMS guides below are the map of what is different. API setup for each channel lives in the docs.
Three resources form a pipeline, each building on the one before it: Contacts → Segments → Campaigns.
Contacts are the people you can email — an address plus optional name and custom fields. They carry a marketing subscription state; an unsubscribed or suppressed contact is never mailed.
Segments are named groups of contacts. A campaign sends to exactly one segment, so a segment is the unit of "who receives this send." Only subscribed members are mailable.
Campaigns combine a template (the content, authored on the Templates page) with a segment (the audience) and a verified from-domain, then send now or on a schedule.
Read the chain bottom-up when something won't send
A campaign can only send if its template is publishable, its segment has subscribed members, and its from-domain is verified. When a send is blocked, walk back down the chain — domain → segment members → template — and the offending link is almost always one of those three.
Deleting a segment or campaign archives it rather than removing it. Archiving keeps history intact and avoids orphaning references. Archived items are hidden from pickers, can be restored, and are swept ~30 days later once nothing active references them.
Active references block destructive actions
You can't archive a segment that a non-terminal campaign (draft, scheduled, sending) needs — cancel or finish that campaign first. This is a clean, explained stop in both the UI and the API.
Each page has its own guide below. New to the product? Follow the sidebar order: verify a Domain, build a Template, add Contacts, group them into a Segment, then create a Campaign.
The Dashboard is the home screen: a summary of sending volume, deliverability signals (bounces, complaints), and recent campaigns and messages. It's a read-only overview — every figure links through to the page where you can act on it.
Use it as a daily health check. A rising bounce or complaint rate, a domain that's slipped out of verification, or a campaign stuck in draft all surface here before they become a deliverability problem.
Start here when onboarding
If your account is new, the Dashboard guides you through the first run: verify a domain, create a template, and send a test. Those are the prerequisites every campaign depends on.
Contacts are individual recipients: an email address plus optional name and custom fields you define. Each contact has a marketing subscription state — subscribed contacts are mailable; unsubscribed or suppressed contacts are skipped automatically and never receive campaign mail.
You add contacts in the dashboard, by CSV import or through the API. A contact is also added automatically when you send a marketing template to an address that isn't one yet: a marketing email's unsubscribe link belongs to a contact. Those contacts show "Created by a marketing send" on their activity.
Custom field defaults
A field's default is the value used for any contact that has none: when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. A value you set on a contact always wins.
Import contacts in bulk from CSV. The import is per-row resilient: valid rows are created even if others fail. You get a summary of imported, skipped, and rejected rows, so one bad line never sinks the file.
Custom-field limits
Custom fields are capped per contact (and on key/value length). Rows that exceed the caps are rejected in the import rather than truncated silently.
A suppression is an address-level block that excludes a single email address from every send — transactional, batch, and campaign — including CC and BCC. The match is case-insensitive. Suppressions keep you from mailing addresses that have already bounced or complained.
When a message hard-bounces or the recipient complains, the address is added to your suppression list automatically and silently skipped on future sends. This is the single most important thing you can do for deliverability.
Add addresses by hand from the Suppressions tab on the Contacts page — paste one or many and they're suppressed in a single step. The same operations are available via API at /api/v1/suppressions.
Excluded, not failed
A send to a suppressed address isn't an error — the send succeeds, the suppressed recipients are simply dropped, and the result tells you how many were excluded and why. One bad address never fails the whole send.
Unitpost also keeps a platform-wide list (reputation and abuse protection) that is checked on every send. Those addresses don't appear in your Suppressions tab or in the API list. Your list only ever holds your own workspace's addresses. When a platform-wide block stops a send, that email or contact shows as Suppressed, and a campaign counts it under Skipped (suppressed). Looking up one address by email still tells you it is blocked platform-wide. These blocks can't be removed from your workspace; if you believe one is in error, contact support.
Any member with the manage-suppressions permission can remove an address you added. Removing an address that previously bounced or complained shows a warning, as re-sending to it can damage deliverability.
A segment is a named audience — a group of contacts a campaign can target. Each campaign sends to exactly one segment, so segments are how you decide who receives a given send.
The list shows each segment's subscribed-member count alongside its total. Only subscribed members are mailable. A segment with zero subscribed contacts is flagged, because a campaign to it can't send.
Empty segments block sends
A campaign whose segment has no subscribed members is stopped before it sends — there's no one to mail. Watch for the "0 subscribed" / "Empty" badge in the list and fix the audience before scheduling.
A rule on a custom field uses the field's default for any contact that has no value, the same value merge tags use. With a Yes/No field that defaults to No, "is No" includes contacts that never had the field set. "Is set" and "is not set" check whether the contact itself has a value. Defaults are never written onto contacts, so changing one updates every segment at once.
Deleting a segment archives it. Archived segments disappear from pickers, but the historical record of campaigns stays intact. You can restore an archived segment, and it's permanently swept ~30 days later once unused.
Can't archive while actively referenced
If a non-terminal campaign (draft, scheduled, sending) still targets a segment, archiving is blocked with a 409 — cancel or finish that campaign first.
API keys authenticate requests to the public v1 API, the SDKs, the CLI and the SMTP relay. Create one under API Keys (also in Settings → Developers), pick what it may do, and copy the secret: it's shown once.
Every key has a scope. Full access can use every API operation except the opt-in ones, which you tick under Advanced: branding:write (branding, the logo, the workspace's name and image, Brand Kits), apikeys:read (your keys and their usage) and activity:read (the activity log). Sending can send email, campaigns and SMS, and read what a sender needs (contacts, templates, domains, sends). Read only can read everything except the opt-in reads, and change nothing. What each one covers:
Area
Full access
Sending
Read only
Emails
Read and send
Read and send
Read
SMS
Read, manage and send
Read and send
Read
Campaigns
Read, manage and send
Read and send
Read
Templates
Read and manage
Read
Read
Contacts
Read and manage
Read
Read
Segments
Read and manage
Read
Read
Topics
Read and manage
Read
Read
Domains
Read and manage
Read
Read
Webhooks
Read and manage
—
Read
On a paid plan you can also pick the exact capabilities a key holds instead of a preset (Advanced, when you create it). The API checks the key's capabilities on every request and answers 403 with the missing permission's name when one is missing.
What no key can do
No key, not even Full access, can manage API keys, the team or billing, delete the workspace, or buy SMS numbers and registrations. Those stay in the dashboard behind a signed-in person, so a leaked key can never widen its own access. Changing branding, Brand Kits and the workspace's name is open to a key only when you tick branding:write on it (MCP's older brand_kits_import also takes templates:write).
A key's scope can't be changed after it's created. To change what an integration can do, create a new key, deploy it, then revoke the old one. Revoking is immediate: the next request with that key gets 401. The SMTP relay's credential is a Sending key, so the same rules apply.
Scope tightly
Give each integration the least it needs: a server that only sends mail gets a Sending key, a reporting job gets Read only. Keys belong to the workspace, and anyone who can manage API keys can see and revoke them.
Pair keys with Webhooks for a full integration: keys for your calls to Unitpost, webhooks for Unitpost's events back to you. People's access is separate: see Team.
Invite teammates under Settings → Team. Each person has a role, and the role sets what they can do. The same permissions model scopes API keys, so a person and a key are limited the same way.
There is one Owner. Only the Owner can manage billing and delete the workspace, and can hand ownership to a teammate (Transfer ownership on their row); the old Owner becomes an Admin. Admins can do everything else, including inviting people and managing keys and webhooks. Members build and send: contacts, templates, campaigns and sends. They can see domains and webhooks but not change them, and can't manage keys, the team or settings.
On a paid plan, open Advanced when you invite someone or edit a member to add or remove single permissions on top of the role, for example a Member who may also verify domains, or an Admin who may not send campaigns. Billing and deleting the workspace always stay with the Owner.
A pending invitation holds a seat until it's accepted, revoked, or expires. An expired one shows as Expired on the Team page and frees its seat; Re-invite sends a fresh link if a seat is free.
The CLI and AI apps connected through MCP sign in as a person and get at most that person's permissions. Each person sees and revokes their own under Settings → Connected apps; Owners and Admins can review and revoke any member's sign-ins from that member's row. Removing someone from the team ends their sign-ins.
Webhooks push events to your application as they happen — a delivery, a bounce, a contact change — so you can react without polling. Register a public HTTPS endpoint, subscribe to the events (or categories) you care about, and we POST a signed payload whenever one fires.
Full reference in the Webhooks guide
This page manages your endpoints; the API-reference Webhooks guide covers the payload shapes, signature verification (including timestamp tolerance), the retry schedule, the HTTPS/SSRF requirement, and rotating the signing secret. Read it before wiring up your verifier.
Each endpoint shows a live health state — Enabled, Failing, or auto-Disabled after sustained failures — so a dead URL surfaces early. Use Send test to fire a sample signed event and confirm your handler works end to end.
A paid plan includes a monthly sending allowance: a dollar wallet you spend on email and SMS, each at that channel's own rate. It refreshes at the start of each billing period and does not roll over. The unused portion carries into the new plan only when you upgrade. Balance, spend, and overage are on Settings → Usage. The plan itself is on Settings → Billing. Current rates are on Pricing.
Email is charged at your plan's rate per thousand messages. Marketing and transactional sends use the same rate.
SMS is charged per segment at the published rate for the recipient's country.
Number and registration fees for toll-free and 10DLC (the monthly number lease, and one-time carrier fees such as brand registration and vetting) are quoted before you confirm, then taken from the wallet. They are not a separate charge on your card.
When the allowance is spent, sending continues and the extra is billed as overage, at a higher rate than your plan. Overage stops at 25% of the monthly allowance (a $30 plan can go $7.50 over), and you get an email when it's half used. After that, sends pause until the allowance refreshes or you move to a larger plan.
You can't buy extra credit. If the workspace already has purchased credit, that balance is spent after the monthly allowance and does not refresh.
Not everything comes out of the wallet
A dedicated IP is a line item on your card. It is not drawn from the sending allowance.
The same snapshot is on the API. GET /api/v1/usage returns the plan, the period, and on a paid plan the wallet in integer cents: allowance, spend, upgrade carryover, purchased credit, and overage. On the free plan wallet is null.
The Migration Assistant (Settings → Migration) moves your data from another email platform into Unitpost in about five minutes. It supports Resend, SendGrid, Mailgun, Postmark, Brevo, Loops, Mailchimp, MailerLite, Kit, beehiiv and Klaviyo, and carries over up to seven kinds of data: contacts (with custom fields and subscription state), segments, topics, templates, domains, suppressions, and webhook endpoints.
Connect — pick your provider and paste an API key (it only ever reads from your old provider; where the provider offers a read-only key, use that). The key is validated, KMS-encrypted, used once to fetch a snapshot, then deleted.
Preview — the assistant fetches everything in the background and shows a full preview: per-entity counts, samples, conflicts with data already in your workspace, and explicit warnings for anything the provider can't export. You can leave the page; the job persists and updates live.
Accept — nothing is written until you accept. Choose which entities to include and how to resolve conflicts (skip or update), then import. A full report shows every row that was imported, skipped, or failed.
For every provider, one API key is all it takes — the assistant does the rest. A few providers have one extra detail worth knowing before you paste the key:
SendGrid — a key with Full Access, or Restricted Access with read permission on Contacts, Marketing, Templates, Suppressions, Sender Authentication, and Webhooks (Settings → API Keys).
Mailgun — your account-level Private API key (Settings → API Security), not a domain sending key.
Postmark — an Account API token (Account → API Tokens) migrates everything in one run: domains plus every server's templates, suppressions, and webhooks. A single Server token also works, but can't read domains.
Brevo — an API key from Settings → SMTP & API. One thing to check first: if your account blocks unauthorized IPs for API keys (Security → Authorized IPs), turn it off before migrating — under “Blocking unauthorized IP addresses”, choose Deactivate for API keys. Brevo rejects API calls from unlisted IPs even when the key is valid. Keys created with the MCP toggle work too.
Mailchimp — an API key created by an Owner, Admin or Manager (Profile → Extras → API keys). Mailchimp keys can't be read-only, so delete this one in Mailchimp once the migration finishes.
MailerLite — an API token from Integrations → MailerLite API, created without IP restrictions. Accounts created before March 2022 (MailerLite Classic) use a different API that isn't supported yet.
Kit — a V4 API key (Settings → Developer → Add a new key). V3 keys don't work.
beehiiv — an API key from Settings → Workspace Settings → API, created by an Owner or Admin. beehiiv asks for identity verification before it lets you create one, and its Free plan allows 30 requests a minute, so a large list takes a few minutes to read.
Klaviyo — a private API key with Read-Only access (Settings → API keys → Create Private API Key → Read-Only Key; Owners, Admins and Managers can create one). Paste the key that starts with pk_: the six-character public key can't read your data.
Read-only on the source — the assistant never sends, changes, or deletes anything on your old provider.
Key custody — the API key is encrypted with KMS the moment you submit it, stored separately from the job, used once for the snapshot fetch, and deleted immediately after (also on failure, cancel, or expiry). It is never shown or re-readable.
Opt-in writes — your Unitpost workspace is untouched until you explicitly accept the preview. Cancel any time before that.
Zero downtime — your current provider keeps sending throughout. Migrate, verify DNS on the recreated domains, then switch your API key over whenever you're ready.
Domains are recreated with fresh DKIM keys — you'll publish new DNS records here; your old provider's records stay valid until you remove them.
Webhook endpoints get new signing secrets, so update your verifier after import.
Templates carry over their HTML and variables; provider-specific template syntax is flagged in the preview when it can't be converted.
Suppressions (bounces, complaints, unsubscribes) carry over so you never re-email someone who opted out.
Consent stays strict: contacts who never confirmed a double opt-in are left out, and an unsubscribed contact stays unsubscribed. Phone numbers (Mailchimp, Klaviyo and others that hold them) arrive as SMS numbers without consent unless the provider recorded the date of the opt-in; SMS opt-outs always carry over.
Newsletter and marketing platforms keep their content on sends, so drafts and recent campaigns or broadcasts come over as templates, with the provider's merge tags converted where the meaning is exact. Automations and flows are listed in the preview, not migrated.
Anything a provider's API can't export is called out in the preview — never silently dropped. The preview expires if unaccepted, and one migration runs per workspace at a time.
Ask AI to help
The Unit assistant in the dashboard can check your migration's status, walk you through the preview, and explain any warning — just ask it about your migration.
Unitpost connects to the tools you already use through its REST API, webhooks and SMTP relay. Each section below is the smallest reliable way to wire one tool in: what fires in that tool, where the API key goes, and the exact call into Unitpost. The vendor details (trigger names, plan limits, quotas) come from each vendor's own docs, checked 2026-10-24. Ask Unit or your own agent (through MCP) for the same advice applied to your setup.
No native apps yet
No native Zapier, Make, n8n, Google Sheets/Forms/Docs, Shopify, HubSpot or Salesforce app yet — connect with a generic HTTP step (Webhooks by Zapier, Make HTTP, n8n HTTP Request) or a small script, using an API key. Unitpost doesn't read Google Docs, Sheets or Notion by itself: something on your side (Apps Script, a no-code step, a script) pushes the data in. For a one-time list, export CSV and use the contact import instead. Unitpost doesn't host signup forms; the form lives in your site or form tool and posts the contact in. No IMAP/POP mailboxes — replies arrive as email.received webhooks. Unitpost doesn't send a third party's own notifications (Stripe receipts, Shopify order emails, Calendly confirmations): if you move those to Unitpost, switch the vendor's version off so people don't get two.
Start from where the data/event begins and the smallest reliable hop: a script in the tool you already use (Apps Script for Google, Run a script in Airtable, a webhook handler in your backend) beats adding a new paid product.
No-code: if you already pay for Zapier, Webhooks by Zapier is fine (it isn't on Zapier's Free plan). On a budget or self-hosting, n8n (HTTP Request node) or Make (HTTP module) do the same. Free Zapier/Make poll every ~15 minutes, so 'instant' needs a webhook trigger or a paid plan.
Payments, stores, auth providers push signed webhooks: verify the signature on the RAW body, answer 2xx fast, and pass the source event id as idempotency_key — every one of them retries and may deliver twice or out of order.
Let the other tool say what happened and let Unitpost decide what to send (an event into an automation, or a new contact into a welcome journey), instead of building the email logic in Zapier.
Only people who opted in or are customers go into Unitpost. A list of scraped, bought, rented or 'found' leads is a no under the Acceptable Use Policy — design an opt-in form instead.
A Google Form is the signup/lead form and each response should become a contact (and get a welcome).
Trigger in the tool: Apps Script installable form-submit trigger (onFormSubmit) on the Form, or on its response Sheet.
How it connects: The trigger's handler reads the answers and calls UrlFetchApp.fetch(POST JSON) to Unitpost.
Where the API key lives: Script Properties (PropertiesService.getScriptProperties()); the script asks once for the external-request permission.
Into Unitpost: POST /contacts, then POST /email with the welcome template.
How fast: Instant, on every submission.
Limit: Apps Script quotas: 20,000 URL fetches/day and 90 min total trigger runtime/day on consumer accounts (100,000 / 6 h on Workspace); 6 min per execution.
Limit: An installable trigger runs as the person who created it — if that account loses access, it stops.
Watch out: A function named onFormSubmit does nothing until the trigger is installed.
Watch out: Turn on the form's 'Collect email addresses' and read getRespondentEmail(); a free-text Email question can hold anything.
Watch out: Ask for marketing consent in the form if they'll get newsletters, not just the welcome.
Contacts or orders live in a Sheet that people (or other tools) keep adding to.
Trigger in the tool: Apps Script installable Edit/Change trigger for rows people type in; a time-driven trigger (every 1/5/10/15/30 min) sweeping unsynced rows for rows other tools write.
How it connects: UrlFetchApp POST per new row; write a 'synced' timestamp (or the contact id) back so a row is sent once.
Where the API key lives: Script Properties.
Into Unitpost: POST /contacts for new rows; POST /email with a template when a row needs an email now.
How fast: Instant for edits; the sweep interval for rows written by other tools.
Limit: A SIMPLE onEdit can't call external APIs (no authorized services, 30 s cap) — it must be an installable trigger.
Limit: Same Apps Script quotas as Google Forms (20,000 fetches/day consumer).
Watch out: Rows written by a script, the Sheets API or Zapier never fire edit/change triggers — use the time-driven sweep for those.
Watch out: Edit triggers fire per cell: wait for a 'ready' checkbox or all required columns before sending.
Watch out: For a one-time list, export CSV and import it in Contacts instead of row-by-row calls.
Watch out: Ask where the list came from first: a sheet of scraped or bought leads can't be emailed (Acceptable Use Policy).
You write the newsletter in a Doc and want to send it with Unitpost.
Trigger in the tool: Manual (a menu/button in a bound script) or time-driven; Docs has no 'document changed' trigger.
How it connects: Simplest: paste the text into a Unitpost template (or give it to Unit to lay out as a designed email). Automated: Drive export (text/markdown, text/plain or text/html) from Apps Script, poured into a template variable.
Where the API key lives: Drive scope for the export; the Unitpost key in Script Properties.
Into Unitpost: Same: a template filled from the export, sent as a campaign after review.
How fast: On demand.
Limit: Drive export is capped at 10 MB.
Watch out: Exported Docs HTML is web HTML (stylesheet classes, not inline email styles) and its images point at Google-hosted URLs — don't mail it raw; use the text and a Unitpost template, and review before a broadcast.
Watch out: getBody() reads only the first tab of a multi-tab Doc.
You already run your glue in Zapier on a paid plan.
Trigger in the tool: Any Zapier trigger (form/sheet/CRM app, Zapier Forms, or Webhooks by Zapier Catch Hook).
How it connects: Action 'Webhooks by Zapier' → POST (or Custom Request), Payload Type JSON, header Authorization: Bearer <key>.
Where the API key lives: The key sits in the step's header — anyone who can edit the Zap can see it; use a key limited to what the Zap does.
Into Unitpost: Webhooks by Zapier POST /contacts, or POST /email with a template.
How fast: Instant for webhook-based triggers; the polling interval otherwise (Google Sheets/Forms on Zapier usually poll).
Limit: Webhooks by Zapier is a premium app: Professional, Team or Enterprise — not on the Free plan (Free is also limited to two-step Zaps and 100 tasks/month).
Limit: Every step run is a task; polling triggers check every 15 min (Free), 2 min (Professional), 1 min (Team/Enterprise).
Limit: Zapier's own MCP offering and an MCP-client step exist; a plain Webhooks step to the REST API is the stabler path.
Watch out: There is no Unitpost app in Zapier's directory yet: use Webhooks by Zapier rather than searching for one.
Watch out: Polling triggers can re-deliver after edits: send idempotency_key on events.
Watch out: Free-plan users can't turn on a Zap with a Webhooks step: suggest Make, n8n or Apps Script instead.
You self-host or want the cheapest no-code glue; also the easiest to point at Unitpost's MCP server.
Trigger in the tool: Any trigger node, Schedule Trigger, or the Webhook node (production URL only once the workflow is active).
How it connects: HTTP Request node, Send Body JSON, credential type Bearer Auth (or 'Import cURL' from the Unitpost docs). MCP Client nodes can call mcp.unitpost.com directly.
Where the API key lives: n8n credentials (stored encrypted, not in the node).
Into Unitpost: HTTP Request → POST /contacts or POST /email with a template.
How fast: Instant with a Webhook trigger; the interval for Schedule/polling triggers.
Limit: n8n Cloud bills per workflow execution (a whole run, any number of steps); self-hosted Community Edition has no execution cap.
Watch out: Test and production webhook URLs differ — 'works in test, silent in production' is usually the test URL.
Watch out: Verify Unitpost webhook signatures in a Code node before trusting them.
Emails driven by payments: welcome after checkout, failed-payment (dunning), trial ending, cancellation.
Trigger in the tool: Stripe webhook events: checkout.session.completed (+ checkout.session.async_payment_succeeded), invoice.paid, invoice.payment_failed, customer.subscription.created|updated|deleted, customer.subscription.trial_will_end (3 days before), invoice.upcoming.
How it connects: Your HTTPS endpoint or serverless function verifies the Stripe-Signature on the RAW body (stripe.webhooks.constructEvent), answers 2xx fast, then calls Unitpost.
Where the API key lives: Stripe endpoint signing secret (whsec_…, different in test and live) and the Unitpost key in env vars.
Into Unitpost: POST /email with the matching template from the webhook handler, idempotency_key = event.id.
How fast: Instant (push).
Limit: No plan gate; up to 16 event destinations; live-mode retries for up to 3 days.
Watch out: No ordering guarantee and duplicates happen: pass the Stripe event.id as idempotency_key.
Watch out: A framework that parses JSON first breaks signature verification — keep the raw body.
Watch out: Stripe can send its own receipts, failed-payment and trial-ending emails: switch those off in Stripe if Unitpost sends them.
A Shopify store wants order follow-ups, abandoned-checkout or post-purchase journeys from Unitpost.
Trigger in the tool: Webhook topics orders/create, orders/paid, orders/fulfilled, checkouts/create, checkouts/update, customers/create.
How it connects: Three routes: a webhook created in Settings → Notifications → Webhooks (no app); a custom or public app subscribing via the Admin API; or Shopify Flow's 'Send HTTP request' action posting straight to Unitpost.
Where the API key lives: Verify X-Shopify-Hmac-Sha256 (base64 HMAC-SHA256 of the raw body); Flow can reference secrets in headers.
Into Unitpost: orders/paid → POST /email with the follow-up template; customers/create → POST /contacts. Abandoned-checkout timing needs automations (or your own delayed job).
How fast: Instant (push).
Limit: Flow's Send HTTP request is on Grow, Advanced and Plus — not Basic.
Limit: Merchants can't create new legacy admin custom apps since January 1, 2026 (existing ones keep working).
Limit: Endpoint must answer within ~5 s; failures retry 8 times over 4 hours, then the subscription can be removed.
Limit: Apps need Shopify's protected-customer-data approval for order/customer fields.
Watch out: An abandoned checkout isn't an event: send checkout started, then let a Unitpost automation wait (e.g. 1–24 h) for order.paid and only remind when it doesn't come.
Watch out: Dedupe on X-Shopify-Webhook-Id (pass it as idempotency_key).
Watch out: Shopify sends its own order and abandoned-checkout emails: turn those off before sending them from Unitpost.
Watch out: Only add customers who accepted marketing as newsletter contacts.
Node.js
const digest = crypto.createHmac('sha256', process.env.SHOPIFY_CLIENT_SECRET).update(rawBody).digest('base64');
const ok = crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(req.headers['x-shopify-hmac-sha256'] || ''));
if (!ok) return res.sendStatus(401);
Your app runs on Supabase: welcome on signup, events from table changes, or sending Supabase's auth emails through Unitpost.
Trigger in the tool: Database Webhooks on INSERT/UPDATE/DELETE (payload: type, table, record, old_record); Auth Hooks (Send Email Hook replaces the built-in auth emails).
How it connects: Database Webhook → Edge Function (fetch to Unitpost), so the key never sits in a trigger. Auth emails: Send Email Hook → Edge Function → POST /email, or point Supabase's custom SMTP at Unitpost SMTP.
Where the API key lives: supabase secrets set UNITPOST_API_KEY=… (read with Deno.env.get); hook requests are signed (Standard Webhooks).
Into Unitpost: insert → Edge Function → POST /contacts then POST /email with the welcome template; auth emails via the hook or SMTP.
How fast: Instant (after commit).
Limit: Send Email Hook is on Free and Pro; hook timeouts: Postgres 2 s, HTTP 5 s.
Limit: Supabase's built-in SMTP sends only a handful of emails per hour (team addresses only) — production auth email needs custom SMTP or the hook.
Limit: pg_net calls time out after 2 s by default and aren't retried — a failed call is silent.
Watch out: Because pg_net doesn't retry, use an outbox table + cron for anything that must not be missed, or check net._http_response.
Watch out: With the Send Email Hook on, SMTP isn't used and you build the confirmation link from token_hash + redirect_to.
Auth by Clerk: add new users as contacts, or deliver Clerk's verification emails through Unitpost.
Trigger in the tool: Clerk webhooks (via Svix): user.created / user.updated / user.deleted; with 'Delivered by Clerk' off on a template, an email event carries the message for you to send (check the exact event name in the Dashboard's Event Catalog).
How it connects: Route handler → verifyWebhook(req) (@clerk/nextjs/webhooks) → Unitpost.
Where the API key lives: CLERK_WEBHOOK_SIGNING_SECRET (whsec_…); Svix headers.
Into Unitpost: user.created → POST /contacts + POST /email; verification emails → POST /email.
How fast: Near-instant but asynchronous and not guaranteed — don't depend on it for sign-in-critical flows without monitoring.
Limit: Opt-out of Clerk delivery is per template.
Watch out: At-least-once, unordered: dedupe on svix-id.
Watch out: If Unitpost sends Clerk's verification codes, an outage in that handler blocks sign-ins.
A Notion database tracks subscribers, leads or approvals.
Trigger in the tool: Notion API webhooks (page.created, page.properties_updated, data_source.content_updated…), or a database automation's 'Send webhook' action; polling a data source as a fallback.
How it connects: API webhooks carry ids only — the receiver reads the row with the Notion API, then calls Unitpost. 'Send webhook' posts properties in Notion's own format, so a relay (n8n/Make/function) reshapes it.
Where the API key lives: Notion integration token; webhook signatures (X-Notion-Signature).
Into Unitpost: relay → POST /contacts, or POST /email.
How fast: API webhooks within minutes (most within a minute).
Limit: 'Send webhook' is on paid plans; API rate limit ~3 requests/second per integration.
Watch out: Delivery can be out of order; on a 'Send webhook' failure the automation pauses until someone resumes it.
Trigger in the tool: Automation trigger 'When record matches conditions' (e.g. a Ready checkbox) or 'When a record is created'.
How it connects: Action 'Run a script' with fetch() to Unitpost; record fields come in through input.config().
Where the API key lives: Airtable script secrets (input.secret('UNITPOST_API_KEY')).
Into Unitpost: Run a script → POST /contacts or POST /email.
How fast: Near-instant.
Limit: Automation runs per month: Free 100, Team 25,000, Business 100,000; a script makes at most 50 fetch calls per run (check whether scripts are on your plan).
Watch out: 'When a record is created' can fire before fields are filled — trigger on a Ready condition.
Trigger in the tool: The tool's native 'new response' webhook (Typeform form_response, Tally FORM_RESPONSE, Webflow form_submission).
How it connects: The native webhook can't reshape its JSON into Unitpost's body, so a small relay (serverless function, n8n, Make, Zapier Catch Hook) maps fields and calls Unitpost.
Where the API key lives: Each tool signs its webhook (Typeform-Signature, Tally-Signature, x-webflow-signature — Webflow only for webhooks created through its API).
Into Unitpost: relay → POST /contacts + POST /email with the welcome template.
How fast: Instant.
Limit: Tally webhooks are free; check Typeform's and Webflow's current plan pages for webhook availability.
Watch out: Answer 2xx fast (Tally times out at 10 s); a 404/410 from the relay disables a Typeform webhook.
Watch out: Add a marketing-consent checkbox to the form before adding people to newsletters.
The CRM is the system of record and Unitpost sends.
Trigger in the tool: HubSpot workflow action 'Send a webhook'; Salesforce record-triggered Flow with an HTTP Callout.
How it connects: HubSpot can map properties into a custom JSON body (no relay needed); Salesforce uses a Named/External Credential for the Authorization header.
Where the API key lives: HubSpot stored secret (format the value as 'Bearer <key>'); Salesforce Named Credential.
Into Unitpost: Send a webhook → POST /contacts, or POST /email.
How fast: Near-instant on enrollment; HubSpot retries for up to 3 days.
Limit: HubSpot 'Send a webhook' needs Data Hub Professional or Enterprise; without it, use a no-code tool polling the CRM.
Watch out: Decide which system owns marketing email and unsubscribes; push Unitpost topic.unsubscribed / email.bounced webhooks back to the CRM.
Trigger in the tool: track (e.g. 'Order Completed') and identify calls.
How it connects: A Segment Destination Function (onTrack / onIdentify) or the Webhooks (Actions) destination; RudderStack's Webhook destination plus a transformation.
Where the API key lives: Function settings (settings.apiKey) / destination headers.
Into Unitpost: onIdentify → POST /contacts; send email from your backend with POST /email.
How fast: Near real time; Segment retries functions that throw RetryError for hours.
Limit: Turn batching off: Unitpost takes one event / contact per call.
Watch out: Map messageId to idempotency_key.
Watch out: An event without an email (or a userId → email mapping) can't reach a contact.
A domain is your sending identity. Before you can send from an address like hello@yourcompany.com, the domain yourcompany.com must be added here and verified by publishing the DNS records we generate (a DKIM TXT record, a custom MAIL FROM subdomain, and a DMARC policy).
Verification runs automatically once DNS propagates — you don't click anything. A domain moves through Pending → Verified; if records change or are removed it can fall back, at which point sends from it are blocked.
Re-checked at send time
A domain's status is verified again the moment a campaign sends, not just when you created it. If the domain isn't in a sending-allowed state at send time, the send is blocked with a clear message — so a domain that lapses after a campaign is scheduled won't silently send unauthenticated mail.
Domains feed directly into Templates and Campaigns: the from-address you pick when sending must belong to a verified domain. This is the first link in the contacts → segments → campaigns chain.
You can also receive mail at your domain. Enable inbound routing on the domain's Receiving tab (or send capabilities.receiving on PATCH /email/domains/{id}) and publish the MX record, and we'll parse incoming mail and POST it to your webhook as clean JSON. See the Inbound email guide for details.
Templates are reusable emails — a subject and a body, authored in one of three editors: Simple (a plain, personal note, like typing in Gmail), Design (built visually from the component library; the default) or Code (your own HTML). A template can be used by a campaign, or referenced by API sends via its id, so you author content once and send it many ways.
Templates carry a category. Marketing templates are the ones campaigns use. Transactional templates are for API-triggered, one-to-one mail (receipts, resets) and are intentionally NOT selectable for campaigns.
You can also send a marketing template through the API to a single recipient. That recipient becomes a contact if they aren't one already, so every marketing email carries a working unsubscribe link.
Transactional templates can't be campaigned
Creating a campaign from a transactional template is blocked by the server (not just the form), because campaign mail to a marketing audience must honor unsubscribe and consent rules that transactional mail doesn't. Use — or clone into — a marketing template instead.
Images and other assets a template references live in the Library; a template that's still a draft, or that references missing assets, can't back a campaign send.
The Library is shared asset storage for your workspace — upload images and files once, then reference them from any template. Hosting assets here (rather than hot-linking from elsewhere) means they stay available and load fast for every recipient.
Assets are referenced by Templates, so deleting an asset that a live template uses will leave a broken image in that mail. Check usage before removing anything you're unsure about.
Keep originals reasonable
Large images slow rendering and can trip spam filters. Upload appropriately sized assets — the Library is for delivery, not as a full-resolution archive.
A topic is a subscription category — "Product updates," "Promotions" — that a contact can opt out of. It's orthogonal to segments and global unsubscribe: a contact can stay on your list but silence one kind of mail.
Manage topics from the Topics page in the dashboard. Recipients control membership via the unsubscribe preference page, and campaigns simply point at a topic to scope a send.
Each topic has one decision baked in — its default — which sets what "no explicit preference" means for a contact who has never touched it:
Opt-out (the default) — contacts are auto-enrolled and receive the topic unless they opt out. Use it for newsletters and product updates.
Opt-in — contacts are silent until they explicitly subscribe. Use it for beta invites or sensitive announcements you don't want going out by default.
An explicit choice always wins
Once a contact subscribes or unsubscribes from a topic, that choice overrides the default in both directions. The default only governs contacts who've never recorded a preference.
Scope a campaign to a topic and anyone opted out is skipped at send (counted as suppressed in the validation report). You can't point a campaign at an archived or missing topic.
One-click unsubscribe respects the topic
Mail for a topic-scoped campaign carries a topic-aware unsubscribe link and an RFC 8058 List-Unsubscribe-Post header, so a recipient's one-click opt-out silences just that topic — not all of your marketing. They keep getting everything else they didn't object to.
Manage topics on the Topics page (or via /api/v1/email/topics) — create, list, edit, and archive. Archiving is blocked (409) while a non-terminal campaign still targets it. A contact's per-topic state is read and set at /api/v1/contacts/{id}/topics.
A campaign is a one-to-many send: a template (content) + a segment (audience) + a from-address on a verified domain, sent immediately or scheduled. Campaigns are the end of the contacts → segments → campaigns pipeline.
A newsletter or an announcement is a campaign, whether you start it here, from the API (POST /api/v1/email/campaigns, then /email/campaigns/{id}/send), the MCP server or the CLI. One request covers the whole audience: we pace the sends, retry temporary failures, add the unsubscribe link and header, and report opens, clicks and bounces together.
You don't have to import contacts first. From the API, a campaign takes up to 5,000 addresses inline as recipients in place of a segment_id: we make a segment from them, and addresses we haven't seen become subscribed contacts, so an unsubscribe is remembered for the next send. A larger list goes in as several campaigns, or as a contact import and a segment.
One API call per recipient runs into the request limit
The API takes 10 requests a second per workspace by default. A script that sends a list as single emails faster than that gets 429 for the rest, and a 429 means that recipient got nothing: nothing queues a refused request for you. If each recipient needs different content, send batches of up to 100, which count as one request each. Rate limits has the details.
Before a campaign sends, every one of these must hold (enforced on the server):
The from-domain is verified and sending-allowed (re-checked at send, not just at create).
There's a non-empty subject (from the campaign or the template default).
The template is a publishable marketing template — not transactional, not an archived/draft template.
The segment is not archived and has at least one subscribed member.
Any schedule is within bounds — not in the past, and no further than 90 days out.
When a send is blocked, the validation dialog lists exactly which gate failed and how to fix it. The API returns the same reasons as a structured 409/422.
The validation dialog also shows who will receive the campaign. Its numbers (Members, Sendable, Suppressed, Excluded, and Missing data when some contacts lack a template variable) filter a read-only list of the segment's contacts, with each one's status and the reason in plain words: unsubscribed, on the suppression list (bounced, for example), opted out of the campaign's topic, excluded from this campaign, or missing a value. Seeing the list needs permission to view contacts; without it the dialog shows the counts only.
A campaign moves through draft → scheduled → sending → sent (or canceled/failed). Terminal campaigns can be archived directly; a non-terminal campaign must be canceled first. Archived campaigns are restorable and auto-pruned after ~30 days.
Scheduling semantics
A schedule in the past is treated as "send now"; a schedule beyond 90 days is rejected at both create and send time. These bounds are consistent across the dashboard and the v1 API.
A draft can be edited from its page or with PATCH /api/v1/email/campaigns/{id}: name, subject, from, preview text, template, segment, topic, tracking, variable fallbacks, exclusions and the saved send time. Changed values get the same checks as create. A value equal to the draft's is no edit, so an integration can send back the object it read.
A scheduled campaign is locked. To change it, unschedule it (the Unschedule button, or POST /api/v1/email/campaigns/{id}/unschedule): it goes back to a draft and its send time is cleared, so the next Send needs a time or null for now. A campaign that has started sending can't be unscheduled; cancel it instead.
Duplicate (POST /api/v1/email/campaigns/{id}/duplicate) copies a campaign's setup into a new draft, never its send time or results. Pass an Idempotency-Key so a retry returns the same copy. The SMS campaign routes work the same way, and the MCP server, SDKs and CLI have the same operations.
A copy mails the whole segment again
Duplicating a canceled or sent campaign and sending the copy reaches everyone in the segment, including people who already got the original. Add them to the copy's excluded_contact_ids first if they shouldn't get it twice.
The Emails page is the message-level log: one row per email sent (campaign or API). Each row shows the recipient, subject, delivery state, and engagement (opens, clicks).
Use it to answer "what happened to this specific message?" — trace a delivery, confirm an open, or see why something bounced or was suppressed.
Suppression is automatic
A hard bounce or complaint suppresses that address, so future sends skip it. You'll see the suppression reflected here and on the contact — it protects your domain's reputation without manual cleanup.
Each API send is one request against your workspace's limit, 10 requests a second by default. A request over the limit is answered 429: that message was not sent and has no row on this page, because nothing queues a refused request for you. If a script sent 1,000 emails and fewer rows are here, the missing ones were most likely refused and not retried.
One message to one person (a receipt, a sign-in code): POST /api/v1/email, one request each.
Many different messages, or your own list from your own script:batches, up to 100 in one request. No contacts needed.
The same content to a list: a campaign, one request for the whole audience, paced for you. It takes a segment, or up to 5,000 addresses inline.
If you loop over single sends anyway, pace the loop under your limit and send every 429 again after its Retry-After. The SDKs and the CLI retry for you; a raw HTTP client does not. Rate limits has the details.
Activity is the cross-resource event feed — domain verifications, template changes, campaign sends, key creation, webhook deliveries, and more, in one timeline. Where the Emails page is per-message, Activity is per-account.
It's the place to reconstruct "who changed what, when" — useful for debugging an unexpected state, confirming an action took effect, or auditing access. Every member can reach it.
SMS runs on the same Unitpost you already use for email: same contacts, same segments, same API key and error envelope, same webhooks. But the channel itself is governed by carriers and regulators rather than inbox providers, and that changes seven things. Each is covered in depth in its own guide; this page is the map.
Paid plans only
SMS is included on every paid plan and is not on the free plan: brands, sender requests, sends, and campaigns need one. On the free plan POST /v1/sms returns 403 with limit_reached. When a paid plan ends, numbers and campaigns are kept for a 7-day grace window and released at its end, with a reminder 7 days and 1 day before.
Email marketing is opt-out by default: you may send until someone unsubscribes. SMS is the reverse. A marketing SMS needs the recipient's prior express consent on record before the first message, and a send without it is skipped with the reason no_marketing_consent rather than attempted. Transactional SMS (receipts, alerts, verification codes) does not need marketing consent. Record consent where the recipient actually gave it: your signup form (POST /v1/contacts/{id}/sms-consent with a source), a join keyword they texted and confirmed with YES (POST /v1/sms/numbers/{id}/join-keywords), or the hosted preference page. Never mark a list as opted in on their behalf. A phone number on a contact (phone on POST or PATCH /v1/contacts) is not consent either: it only says where to text. To confirm an opt-in you recorded, POST /v1/contacts/{id}/sms-opt-in-request texts them "Reply YES"; their YES records a verified marketing opt-in.
STOP opts the number out of the SMS channel entirely. It never touches the contact's email subscription, and vice versa.
HELP returns your program's help text (your brand name, how to reach support, how to stop).
START re-opts the number in. Carrier keywords are handled for you; do not build keyword handling yourself.
Email lands whenever you send it. Marketing SMS respects the recipient's local quiet hours: a message queued at midnight is deferred to the morning window, never dropped and never sent at 2am. The recipient's window comes from their phone number's country and region. A deferred message shows the reason quiet_hours_deferred; there is nothing to fix. Transactional messages are not window-gated.
SMS is included on paid plans, and it spends the same monthly sending allowance as email: one wallet, not a separate SMS balance. Email is charged per thousand messages; SMS is charged per segment at the published rate for the recipient's country. 160 GSM-7 characters fit one segment (153 each when a message spans several); Unicode messages fit 70 (67 each when split). The composer and the template editor show the segment count as you type. A skipped recipient is never billed, and a campaign pauses rather than overdrawing the wallet. Number leases and carrier fees are quoted before you confirm and taken from the same wallet, never charged to your card separately.
A verified email domain can send to any inbox in the world. An SMS sending identity delivers to specific countries, by carrier rule. A US toll-free or 10-digit local (10DLC) number reaches US recipients only; a Canadian local number (instant, no registration) reaches Canada only. To reach other countries you enable an alphanumeric Sender ID: your brand name on the handset instead of a number, free, enabled per destination country. It is instant in most of Europe, Latin America, Asia-Pacific, and Africa; some countries (the United Kingdom, Spain, Singapore, and others) require a regulator registration that takes days to weeks; the United States, Canada, and China do not support Sender IDs at all. A recipient outside every sender's reach is skipped as out_of_reach, with the country and a link to the fix. See SMS Senders for the full reach table.
Carriers report three things: sent (accepted by the carrier), delivered (confirmed on the handset), and failed, with a carrier reason when there is one. There is no open tracking, no click tracking, and no engagement rate to request; the SMS dashboard and the per-message page show delivery, not engagement. If you need a click signal, link to a page you control and measure there.
Email setup is DNS records on a domain you own. SMS setup starts with a brand: your legal entity, website, and a contact email on that website's domain, which carriers or regulators approve before they will hand you a production number or a registered Sender ID. The brand page lists exactly which fields are still missing, and GET /v1/sms/brands returns the same status and missing list for scripts and agents. Creating a brand is free, from the dashboard or POST /v1/sms/brands; registering it with carriers and ordering numbers are paid steps, priced first and then confirmed, in the dashboard or by API (POST /v1/sms/quotes, then its confirm). See SMS Brands and setting it up with an agent.
Email tells you about bounces and complaints after the fact. SMS tells you before you send who will be skipped and why, and every surface uses the same seven words: campaign preflight, the campaign page, the message log, error.code on GET /v1/sms/{id}, and reason on the sms.suppressed webhook.
out_of_reach: no sender on the message or campaign covers the recipient's country. Fix: request a sender for that country.
unsupported_country: inside reach, but Unitpost has no compliance rule for the country yet (transactional still sends), or SMS to that country is paused for now. A pause covers every message, transactional included: a new send is refused with 403 unsupported_country, and a queued one is skipped without charge. It resumes on its own.
no_phone: the contact has no SMS number. Fix: add one to the contact.
opted_out: STOP, the suppression list, or an unreachable number. The recipient re-opts in by texting START or from the preference page.
no_marketing_consent: marketing without express consent on record. Fix: record consent the recipient actually gave.
quiet_hours_deferred: held for the recipient's local window. Delayed, not dropped; nothing to fix.
sender_not_active: the sender lost approval or was released. Fix or replace the sender, then resume.
Before you can get a production phone number, carriers need to know who is sending. A brand is that record: your legal entity, your website, and a contact email on that website's domain. It is the first step in SMS setup and every number you request is tied to one. Brand registration needs a paid plan. New to the channel? Start with SMS vs email.
One brand covers both number types, so you fill this in once. A toll-free number needs the brand complete; a 10-digit local number additionally needs the brand verified with carriers, which adds a tax ID and a one-time fee. If your brand is missing something, the brand page lists exactly which fields are still required.
The contact email has to be on the same domain as the brand website. Carriers use it to confirm the business is really yours, and a mismatch is one of the most common rejection reasons, so we check it up front rather than letting a submission fail days later.
A brand is registered with US carriers, and the US numbers it backs (toll-free and 10-digit local) deliver to US recipients only — see the reach table in SMS Senders. A Canadian local number on the same brand reaches Canada (no registration; the brand is its owner, not a filing). Reaching other countries needs a Sender ID enabled for that country (free; see SMS Senders); a few countries still need a locally issued number, which is not available in Unitpost yet.
Some countries' regulators want to see company paperwork before they approve a Sender ID: a registration certificate, a letter of authorization (sometimes one per mobile carrier), the signatory's ID, a business number such as an Australian ABN. Those are facts about your company, not about one country, so they live on the brand — in the collapsed Company documents section at the bottom of the brand page, or in the optional last step when you create a brand. Upload each once and every country that needs it can use it.
Each row is one document type. It shows the file on record (name, date), lets you download, replace or remove it, and the flags of the countries it unlocks.
PDF, PNG or JPEG, up to 3 MB per file. If a file is bigger, compress it (most PDF tools have a "reduce file size" option).
Documents are not locked when a brand is approved: you can add an Irish certificate after your US 10DLC brand is verified.
A document that a registration under review used can't be removed until the regulator answers; replacing it is how you respond to a correction request.
If one country wants a different version of a document other countries accepted (the Philippines asks for your articles of incorporation, say), upload a version for that country only: Only for <country> in Fix & resubmit, or Upload a version for one country in the document's menu. Every other country keeps the shared file, and a registration that is already approved keeps the file it was approved with.
Privacy
Documents are stored encrypted in private storage scoped to your workspace and are only ever sent to the carrier registry of a country you request a Sender ID for, as part of that registration. Each registration records exactly which version of each document it submitted. Unitpost does not review documents itself — the regulator does, and any correction request shows up on the Sender ID with the document it concerns.
By API, the same library: GET /v1/sms/brands/{id}/documents lists it, POST adds a document from a file you hand over first with POST /v1/files (purpose sms_document) or, for the business number, as text, and DELETE removes one. A person's ID document opens only with the sms:manage scope.
An approved brand is locked
Once carriers approve a brand, or a phone number is attached to it, its details are locked — editing them would invalidate what was approved. If your business details change, or you are sending on behalf of a different company or website, create a second brand instead. If carriers ask for a correction, the brand unlocks for exactly that.
Check readiness from your code
GET /v1/sms/brands returns each brand's status plus a missing list, so a script or agent can report whether SMS is ready without opening the dashboard. A script or agent can also create and edit a brand (POST and PATCH /v1/sms/brands, free), add its company documents (POST /v1/sms/brands/{id}/documents with a file from POST /v1/files), and register it with carriers (a quote, then its confirm, which needs sms:purchase). See setting it up with an agent.
Entered once, reused for every registration
Your brand's legal name, address, website, contact, industry and company ID are what carriers and regulators verify — for toll-free verification, 10DLC brand registration, and every Sender ID registration abroad. Unitpost maps the same brand onto each regulator's form, so a UK or Spanish Sender ID registration asks only for what that country needs beyond the brand. The brand also carries its one Sender ID string (defaults to the brand name) and its company documents; country-specific answers stay on the registration, never on the brand.
SMS needs an origination identity the way email needs a verified domain. Start with the sandbox sender: it works immediately but only delivers to verified test numbers (a carrier rule for unverified senders). For production, New sender asks which countries you'll text and lists what each one needs: a US toll-free or 10-digit local number for US recipients, a Canadian local number for Canadian recipients, or an alphanumeric Sender ID for everywhere else. All of them need a brand first — see SMS Brands. Requesting a number or a Sender ID needs a paid plan. New to the channel? Start with SMS vs email.
Each number also carries a use case: what you send and how people opt in. Carriers read it to decide whether to approve the number, so it is submitted with the request and shown under the number afterwards. If you already have a number, the next one can reuse those answers instead of retyping them.
A sender moves through registration and verification states before it's active, and its status is re-checked at send time — a suspended or released number can't silently keep sending. The monthly number lease and the one-time carrier fees are quoted before you confirm, then taken from the sending wallet. See Wallet.
Everything New sender does is on the API too: a 10DLC number comes with its campaign, a toll-free number is a quote with the opt-in screenshot as a file (opt_in_evidence_file_id), a Canadian number is a quote by country. When carriers send a number's verification back, GET /v1/sms/numbers shows their feedback; fix the brand or the use case and resubmit with POST /v1/sms/numbers/{id}/resubmit (free). Releasing a number is POST /v1/sms/numbers/{id}/release. See setting it up with an agent.
Every sending identity has a reach: the countries it can deliver to. It is a carrier rule, not a setting, and it depends on the kind of identity. Unitpost shows it as a flag next to every number (hover it for the list) and states it in the New number menu and both wizards before you pay for anything.
Toll-free number — US only. International sends from a toll-free number are routed best-effort through a shared identity, losing your brand and with no delivery guarantee; Unitpost does not forward them.
10-digit local (10DLC) number — US only, by carrier rule.
Canadian local number — Canada only. A 10-digit number issued in Canada (a long code), requested by picking Canada in New sender: no brand or campaign registration, active within minutes, a small monthly fee. A US toll-free number never reaches Canada, so sending to both countries takes both numbers. Replies (STOP, ARRET, HELP) come back to Unitpost like a 10DLC number's do.
Sandbox — US only, and only to your verified test destinations.
Alphanumeric Sender ID — the country it is enabled for. Enable one Sender ID per country; US, Canada and China do not support Sender IDs at all.
Short codes and other countries' long codes — the country they are issued in. Not available in Unitpost yet.
An alphanumeric Sender ID is a name of up to 11 letters, digits or hyphens (at least one letter; no leading or trailing hyphen) that appears on the recipient's phone instead of a number — "Acme" rather than +44… . Sender IDs are free: there is no purchase and no monthly fee. Each brand has one Sender ID string (derived from the brand name; change it on the brand), and you enable it per destination country by picking those countries in New sender (or Add countries on the Sender ID). Each enabled country appears as its own row in the numbers table with the country flag.
Instant countries (most of Europe, Latin America, Asia-Pacific and Africa): the Sender ID is requested directly and is active within a minute.
Registration-required countries (for example the United Kingdom, Finland, Spain, Singapore, Belarus, Kazakhstan): the regulator reviews a registration first. It is composed from your brand and use case; a few countries ask for one or two extra answers — Spain's alias holder details — and only those are asked. Singapore's letter of authorization comes from the brand's company documents. Approval takes days to weeks; the row shows the regulator's status and, if it comes back, what to fix and a Resubmit button.
Countries whose registration needs company documents (for example the UAE, Ireland, Saudi Arabia, Turkey, Vietnam, the Philippines, Indonesia) are unlockable: the dialog shows which documents each one needs, and the moment your brand holds them the country becomes requestable. Missing ones are named — "needs: registration certificate" — with a link to the brand's Company documents section. Documents are sent to that country's registry as part of the registration, and a correction request about a document shows on the Sender ID with a Replace link. India needs a separate DLT registration and is not available.
Unregistered Sender IDs get rewritten
In a country that requires registration, an unregistered Sender ID is replaced by the carrier with "NOTICE" ("LIKELY-SCAM" in Singapore and Ireland) and the message may not be received. Unitpost therefore never sends from a Sender ID in such a country until its registration is approved — the sender stays pending until then.
Sender IDs are one-way
Recipients can't reply to a Sender ID, so there is no STOP by text. Marketing sent from a Sender ID must still be opt-out-able: include a link to the hosted preference page in the message, or record opt-outs through POST /v1/contacts/{id}/sms-consent. Consent rules are unchanged — marketing needs express consent on record regardless of the identity.
Out-of-reach recipients are skipped, not attempted
A message to a recipient outside the sender's reach is not sent: it lands as suppressed with the reason ("This number sends to US recipients only") and is never billed. The country comes from the phone number itself — a Canadian or Caribbean +1 number is labelled CA or its island, not US. Campaigns tell you how many recipients this affects before you send, and the public API returns each number's reach (GET /v1/sms/numbers → reach).
Keep marketing and OTP apart
Carriers degrade deliverability for numbers that mix bulk marketing with time-sensitive transactional traffic. When you start sending campaigns, add a dedicated marketing sender so a blast can never slow your verification codes.
The SMS log shows every message your workspace has sent or received, live — queued, sent, delivered, or failed, with the carrier's failure reason when there is one. Each row opens a per-message page with the sender number, segments billed, and the carrier's event timeline. Billing is per segment: 160 GSM-7 characters fit one segment (153 each when a message spans several); Unicode messages fit 70/67. The composer shows the segment count as you type. Sending needs a paid plan. New to the channel? Start with SMS vs email.
Marketing SMS is held to a stricter bar than email: the recipient must have prior express consent on record, and sends respect recipient-local quiet hours (a marketing message queued at midnight is deferred to the morning window, never dropped and never sent at 2am). Transactional messages — receipts, alerts, verification codes — are not window-gated.
STOP always wins
When a recipient replies STOP, the carrier and Unitpost both record the opt-out immediately. Further sends to that number are suppressed on the SMS channel — it never touches their email subscription, and vice versa.
Your toll-free, 10DLC and Canadian numbers receive replies; Sender IDs are one-way (the Phone numbers page marks which is which). A reply shows in the log as Inbound with the text, the number it came from, and a link to your message it answers when the carrier says which. Reply opens the composer addressed to that person from the same number. Each text you receive costs $0.008 a segment in the US and $0.004 in Canada, counted the same way as a send; the message page shows what it was billed. Each one also fires the sms.received webhook, which is how an app or an AI agent answers in its own words; see the SMS API's Start page.
Keyword replies are handled for you. STOP, CANCEL, END, QUIT, UNSUBSCRIBE and the other opt-out words opt the number out; START and UNSTOP opt it back in; HELP and INFO get your registered help text. Only a text that is just the keyword counts, so "please stop texting me" is a normal reply. A one-word answer such as "Cancel" is an opt-out, so phrase questions so that a single word answer can't be one ("Reply 1 to keep, 2 to move").
SMS templates are plain text with the same {{variable}} merge fields as email templates — {{first_name}} and your custom contact fields resolve per recipient at send time, and a send fails closed rather than shipping a literal token. The editor shows the live segment count as you type (160 GSM-7 characters per segment; 70 for Unicode). New to the channel? Start with SMS vs email.
Templates start as drafts; publish one to use it in sends and campaigns. For marketing messages, end with an opt-out hint like "Reply STOP to opt out" — STOP is honored automatically either way.
SMS topics work like email topics — contacts opt in and out per category — but the preferences are tracked per channel: "Product updates" can be on for email and off for SMS for the same contact. A campaign tied to a topic skips recipients who opted out of it. New to the channel? Start with SMS vs email.
STOP always wins on top: a recipient who replies STOP is suppressed on the SMS channel entirely, regardless of topic preferences — and it never touches their email subscription.
An SMS campaign sends a published SMS template to every reachable contact in a segment. Marketing SMS is held to the strict bar: only recipients with prior express consent on record receive it, sends respect the recipient-local quiet-hours window (a blast fired at midnight waits for the morning window — deferred, never dropped), and delivery is paced to your sender's carrier throughput. Sending a campaign needs a paid plan. New to the channel? Start with SMS vs email.
As soon as you pick a segment and a sender, the form checks every contact in the segment and tells you the outcome before the draft exists: how many will be reached, and how many will be skipped and why — outside the sender's reach (with the countries), without marketing consent, opted out, or without a phone number. "See who" lists them with a link to each contact. The send confirmation repeats the count, so the number on the button is the number that goes out.
Reach is decided per recipient from the phone number's country and the sender's reach (see SMS Senders). A US toll-free or 10DLC number reaches US recipients only, so a UK contact in the segment is skipped with that reason rather than attempted; the skip is never billed. Each skipped country comes with what would fix it and, when Unitpost can provide it, a link that opens the sender wizard on that country — "Request a United Kingdom sender →", "Request a Canadian local number →" — so the fix is one click away. A country that is not available yet says so plainly. Reach is not the only gate: a marketing campaign is also held to the countries Unitpost has a quiet-hours rule for (the US and Canada today), so a recipient a Sender ID reaches in a country without one is reported up front as unsupported_country rather than skipped after you press Send.
Every place that says a recipient was skipped uses the same seven words, so what the form warned about is what the campaign page, the message log, the API and your webhooks report: out_of_reach (no sender covers the recipient's country), unsupported_country (Unitpost has no compliance rule for the country yet), no_phone (the contact has no SMS number), opted_out (STOP, suppression list, or unreachable), no_marketing_consent (marketing without express consent), quiet_hours_deferred (held for the recipient's local window — delayed, not dropped) and sender_not_active (the sender lost approval). Each comes with a sentence saying what would fix it. The public API returns the code as error.code on GET /v1/sms/{id}; webhooks send it as reason on sms.suppressed.
Budget pauses, never surprises
If your messaging balance runs out mid-campaign, the campaign pauses — remaining recipients are untouched and you get an email saying why. The same happens if the sender number loses its approval before the send starts. Billing is per segment actually sent.
Click a campaign to open its page. It shows the sender, template, segment and topic it was built from, then the carrier's numbers: recipients admitted, sent (accepted by the carrier), delivered (confirmed on the handset), failed, suppressed (no consent, STOP, blocklist, or outside the sender's reach), deferred (held for quiet hours), and segments billed. Below that, every recipient is listed with the carrier's status and the reason where one was reported — a failed render, a missing opt-in, a carrier rejection — and the campaign's own activity log. The page updates live while a campaign sends.
From the campaign page you can send a draft, duplicate a campaign into a new draft, cancel one that is scheduled, sending or paused, and delete drafts and finished campaigns. Every send, delivery, failure, opt-out and inbound reply on the channel also appears under SMS activity.
The SMS dashboard summarizes the channel's last 30 days: how many messages went out, how many the carriers confirmed delivered, and how many failed or were suppressed. It's the channel-scoped counterpart of the email dashboard — same idea, SMS-honest numbers (no opens or clicks; carriers don't report them). New to the channel? Start with SMS vs email.
From here, jump into the message log for per-message delivery detail, or into Senders to provision an origination number.
SMS Activity is the same workspace activity stream you know from email, locked to channel messages: sends, delivery receipts, retries, and opt-outs (STOP). Use it to answer "what happened on SMS recently" without scanning the full cross-resource feed. New to the channel? Start with SMS vs email.