What is identical
One account has one balance, one rate card and one report. A message costs the same whether it left from the composer or from a script, appears in the same list, and triggers the same webhooks. Everything that decides delivery is shared too: the one route per destination, the sender rule of each country, the encoding rules (160 GSM-7 characters or 70 in Unicode for a single message, up to 6 parts), the billing point (a message is billed when it is handed to a carrier, and a rejected one never is) and the statuses from queued to delivered. The choice is about workflow, not price or quality.
Five questions that decide
| Question | Panel | API |
|---|---|---|
| What starts the send? | A person with a list and a message | An event in your system: a sign-up, an order, an alert |
| Where do the numbers live? | In a file: CSV, TXT or XLSX | In your database |
| Who writes the text? | A person, with {column} placeholders | Your code, for each recipient |
| When must it leave? | Now, at a fixed moment, or in a local-time window | Seconds after the event, or at a send_at |
| Who reads the result? | People, in the live report | Your system, through webhooks |
Answers that fall on both sides are normal. That is the mixed setup described below, and it is where most accounts end up.
When the panel wins
A campaign is a file, a text and a date. The composer does the work that a script would otherwise have to do by hand:
- Import. CSV, TXT or XLSX, files up to 50 MB and up to 1,000,000 numbers per campaign. Numbers are normalised to E.164, with a default country for local formats; duplicates are merged after normalisation; invalid rows are listed, never sent and never billed.
- Text. Placeholders such as
{first_name}, a counter that shows the encoding, the segment count and the longest rendered row, and the name of any character that forced Unicode, with one-click replacements for curly quotes, long dashes, the ellipsis character and special spaces. - Cost preview per destination, before anything is charged.
- Timing. Send now, at a fixed moment or in a local-time window per destination, with quiet hours applied inside the window, a pace per minute or spread over a number of hours, and pause and resume.
Marketing teams, support teams and anyone sending a few campaigns a week rarely need more. The rate is locked for the life of a campaign, so a send paced over three days is billed at the rate the preview used. The guide to preparing a contact list covers the import in detail.
When the API wins
Codes, alerts, receipts and anything triggered by an event in your system belong in the API: one request per message, an Idempotency-Key so retries are safe, a webhook so your system knows what landed, and a reference of your own echoed in responses and webhooks. Bulk sends from your own data pipeline use the batch endpoint, up to 1,000 messages per request. A malformed request is refused as a whole; otherwise invalid items come back as rejected with their error while the valid ones are queued, and the response lists batch_id, accepted, rejected, total_price and the messages. There is more on batch rejections.
Two differences from the composer matter. The API never rewrites text: it returns encoding and segments, and the curly apostrophe the composer would have offered to replace is yours to catch. And timing is set per message: send_at for a fixed moment, a window with local start and end times for local-time delivery, validity for how long the message may wait, and, on batches, a pace per minute or spread over a number of hours. An OpenAPI description and SDK samples in cURL, Python, Node, PHP and Go shorten the first integration; start from the quickstart.
Using both
Most accounts do. Three shapes, as examples:
- A shop. Order confirmations and dispatch notices leave through the API from the order system; a monthly promotion goes out from the panel, built on a customer export.
- A software product. Sign-in codes and incident alerts go through the API, each on its own key; release announcements go from the panel.
- A clinic. The next day's appointment reminders leave as one nightly batch; a closure notice is typed in the panel when it happens.
Three rules keep them from stepping on each other. Tag API messages with a campaign so they group like panel campaigns in the report. Use a separate key per system, so revoking one does not stop the others. And agree who watches the shared balance, so a runaway script never stalls a campaign the marketing team scheduled for tomorrow.
Keys, scopes and allowlists
Keys are bearer tokens: sk_live_ for real traffic, sk_test_ for development. Each key is scoped to send, read or both, and can be limited to an IP allowlist; requests from other addresses get 401. There is no separate developer plan or approval step: the account that sends from the panel creates a key and sends from code a minute later.
- One key per system. The code service, the order system and the reporting job each hold their own. The limit of 50 requests per second applies per key, so a bulk job cannot use up the budget your codes need.
- Smallest scope. A dashboard needs read, a notifier needs send, and few systems need both.
- Allowlist fixed addresses. Servers with stable outbound addresses should be allowlisted; for functions whose addresses change, rely on scope and careful storage instead.
- Live keys stay on servers. A key shipped in a mobile app or a web page can be extracted by anyone, so send from your back end.
- Test keys first. They validate, price and answer like live keys, return the status test and fire signed webhooks, but send and bill nothing.
Tagging so reports line up
Two fields do the work. campaign, up to 64 characters, is the group: messages with the same tag sit together in reports, like a panel campaign. reference, up to 128 characters, is the individual: your order number, appointment id or verification id, echoed in responses and webhooks so every event finds its record.
- Name campaigns by purpose, not by day:
otp-login,order-dispatched,reminder-24h. Timestamps already say when. - Use a different tag for each variant you want to compare, so a split test reads as two lines in the report.
- Keep personal data out of both fields; an internal id is enough to join on.
- Agree the names across teams once, in writing, so the panel and the API never invent two tags for the same stream.
Reports, whichever way you sent
Every message, from either side, lands in the same delivery report: live statuses, failures grouped into about twelve plain reasons with the raw carrier code, one-click removal of unknown numbers, and exports in CSV or JSON with message id, number, status, carrier code, timestamps and price. The from field always shows the sender actually used, which matters wherever a name is replaced by a number. Per-message records are kept for 90 days and campaign summaries indefinitely, so archive exports if you need message-level history for longer.
API traffic adds a real-time view: webhooks push each status into your own system as it changes, which is where operational alerts belong. People read the report; systems read the webhooks. Neither replaces the other.
Moving from one to the other
Move a panel routine to the API when the same export is uploaded every week, when the text needs data that someone pastes by hand, or when the send should follow an event rather than a calendar. Start with a test key, rebuild last week's campaign as batches, and compare the total price with the panel's preview before going live.
Move the other way when a developer is asked to "just send this to everyone". A one-off announcement gains more from the cost preview, the encoding warnings, the local-time window and the pause button than from a script written in a hurry.
Something unclear or out of date? Tell us on the support page; corrections are folded back into the guide and the update date changes.
