SMS Campaigns

SMS Designer (smsdesigner.inklura.fr) composes and sends SMS campaigns. Campaigns are stored in your organization's space, and sending goes through the platform's SMS carrier. The carrier credentials stay server-side and never reach the browser.

The campaign action API

Campaigns are managed through a single endpoint, protected by the session and scoped to your organization:

GET  /api/campaigns            list your campaigns (most recently updated first)
GET  /api/campaigns?id=<id>    one campaign, with its recipient breakdown
POST /api/campaigns            run an action

GET /api/campaigns?id=<id> returns { ok, campaign, recipientCount, breakdown, brands }: breakdown gives, list by list, how many contacts are taken, and brands lists the brands accepted by the setbrand action.

The operation is chosen by the action field in the JSON body. Actions on an existing campaign also take its id:

action Effect
create Create a campaign (as a draft). Returns { ok, id, campaign }.
update Update a campaign. Editing a sent or scheduled campaign turns it back into a draft.
delete Delete a campaign.
preview Live recipient breakdown for targets, listId and extraTo. Nothing is changed or sent.
send Resolve and de-duplicate recipients, then send immediately.
schedule Resolve and de-duplicate recipients, then schedule the send for when.
share Create (or return) the public report link. Returns { ok, token, url }.
unshare Revoke the public report link.
setdelivery Store the real delivery rate read from the carrier.
setbrand Set the brand shown on the campaign's report (brand).

Campaign fields

create and update accept the following fields (all optional):

Field Type Rule
name string At most 100 characters. Defaults to "Nouvelle campagne".
body string The SMS text, at most 4,000 characters.
sender string Sender name. Only the first 11 characters are passed to the carrier.
route "N" or "M" Traffic class (see below). Defaults to N.
targets { listId, cap }[] Contact lists to target (at most 50). cap limits how many contacts are drawn from that list; 0 = no limit.
listId string Older single-list form, uncapped. Ignored when targets is set.
extraTo string Numbers added by hand, separated by commas, semicolons or line breaks.

Lists are processed in order. A number already taken by an earlier list does not count towards the next list's cap, then the extraTo numbers are added if they are not already in the send.

POST /api/campaigns
{
  "action": "create",
  "name": "Summer sale",
  "body": "Our summer sale starts tomorrow.",
  "sender": "MYSHOP",
  "route": "M",
  "targets": [{ "listId": "<list id>", "cap": 500 }]
}

Sending and test mode

send and schedule accept "test": true: the request goes to the carrier's test endpoint, nothing is sent, and the campaign status is left unchanged. The response is { ok, mode: "test", recipients }, where recipients is the number of resolved recipients.

A real send returns { ok: true, campaign, recipients, balance } (balance: the credit balance reported by the carrier, when it provides one). If the carrier rejects the send, the campaign moves to the failed status and the response is a 502 with the reason in error.

Campaign statuses: draft, scheduled, sent, failed.

Message outside a campaign

For a single message or a test send outside a campaign, use:

POST /api/sms/send
{ "text": "…", "to": "06 12 34 56 78, 07 …", "listId": "<optional list>", "sender": "MYSHOP", "route": "N", "test": true }

to takes an array of numbers, or a string of numbers separated by commas, semicolons or line breaks (spaces inside a number are allowed). Numbers from listId are added to those in to, without duplicates. The response returns the kept numbers in recipients.

Number format

Numbers are normalized to international format without +: spaces, dots, dashes and parentheses are removed, a + or 00 prefix is dropped, and a 10-digit French number (06…) becomes 336….

Traffic class

Every send belongs to a traffic class, set with the route field:

route Class Use
N Notification Transactional messages (default).
M Marketing Promotional messages.

Errors

Error responses have the shape { "ok": false, "error": "…" }:

Status Case
400 Invalid JSON body, unknown action, empty message, no recipients, invalid when.
401 No session.
404 No campaign for this id.
500 SMS sending is not configured for the platform.
502 The carrier rejected or could not process the send (not enough credits, invalid or STOP-listed number, etc.).

Scheduling

A schedule action takes a when value (yyyy-mm-dd hh:mm or yyyy-mm-ddThh:mm, seconds optional) and hands the campaign to the carrier with that send time. The carrier holds the batch and sends it at that time. Once a campaign is scheduled, Inklura does not fire it again on its own.

Warning

Editing a scheduled campaign turns it back into a draft in SMS Designer, but does not cancel the batch already handed to the carrier: the scheduled send still goes out.

Reports and delivery rate

Each campaign can expose a public, no-login report page:

/rapport/<token>

The token is the access control: the share action creates it and makes the report reachable (calling it again returns the same link), unshare revokes it and the URL stops working immediately.

Warning

The delivery rate is an estimate until someone enters the real figure. The carrier does not send delivery receipts, so:

  • Delivered defaults to a benchmark estimate (95%). It becomes a real figure when someone reads the campaign's rate from the carrier and enters it with the setdelivery action (rate field), which accepts a fraction (0..1) or a percentage (0..100). A rate of 0 or less clears it. The optional source (40 characters) and period (16 characters, for example 06/2026) fields are shown next to the figure.
  • Read is always a benchmark estimate (95%).
  • Clicks are measured, from the tracked short link in the message.

Treat the delivery rate on a report as entered data, not a measurement.

POST /api/campaigns
{ "action": "setdelivery", "id": "<id>", "rate": 97.4, "period": "06/2026" }

Related