SMS Campaigns

SMS Designer (smsdesigner.inklura.fr) composes and sends SMS campaigns. Campaign records live in the per-app bext KV store; the actual delivery goes out through the Capitole Mobile gateway.

The Capitole Mobile gateway

Sends are POST application/x-www-form-urlencoded with a single form field XML=<payload> to:

https://sms.capitolemobile.com/api/sendsms/xml_v2

A test/echo endpoint mirrors the request without sending (no send, no cost), useful for validating a payload:

https://sms.capitolemobile.com/api/sendsms/xml_test

The XML payload carries three parts:

Part Fields
Auth username, password
Message text, sender, route, prog
Recipients the resolved, de-duplicated recipient list

route selects the traffic class:

route Meaning
"N" Notification (default)
"M" Marketing

prog is an optional server-side schedule in yyyy-mm-dd hh:mm:ss — see Scheduling below.

A send is considered successful when the response body contains:

SENDING_OK;<balance>

Credentials are per-site environment variables, CAPITOLE_SMS_USERNAME and CAPITOLE_SMS_PASSWORD — they never reach the browser.

The campaign action API

Campaigns are managed through one session-guarded, tenant-scoped endpoint:

POST /api/campaigns

The operation is chosen by an { action } field in the JSON body:

action Effect
create Create a campaign record.
update Update a campaign record.
delete Remove a campaign record.
preview Live recipient breakdown — no mutation, nothing is sent.
send Resolve + de-duplicate recipients, then call Capitole immediately.
schedule Resolve + de-duplicate recipients, then call Capitole with a prog time.
share Mint a public report token.
unshare Revoke a public report token.
setdelivery Store the real delivery rate read manually from the Capitole portal.
setbrand Set the brand for the campaign / its report.

Both send and schedule resolve and de-duplicate the recipient set before handing it to Capitole. For a single message or a test send, use:

POST /api/sms/send

KV storage

Campaign records are stored in the app's bext KV namespace under a tenant-scoped key:

smscampaign/<tenant>/<id>

Public report tokens (minted by share) are stored under:

smsreport/<token>

Scheduling

Note

There is no local cron or queue for SMS sends. Scheduling is delegated entirely to the gateway: a schedule action calls Capitole with the prog field set to yyyy-mm-dd hh:mm:ss, and Capitole holds and dispatches the batch at that time. Inklura does not re-poll or re-fire the send itself.

Reporting and the delivery-% honesty flag

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

/rapport/<token>

The token is the access control — minting one with the share action makes the report reachable; unshare revokes it.

Warning

Delivery and read rates are estimates unless an operator enters the real figure. There is no delivery-receipt (DLR) callback from Capitole, so:

  • Delivered / Read default to a benchmark estimate (~95%). They only become real when an operator reads the per-campaign figure from the Capitole portal and enters it via the setdelivery action (which accepts either a 0..1 fraction or a 0..100 percentage).
  • Click metrics are real — they come from the short-link click log.

Treat the delivery percentage on a report as human-entered data, not a fetched metric.

Related