Launch an SMS campaign

Goal: send one SMS to many recipients using the Broadcast surface.
Prerequisites: an API key with the Broadcasts scope (and Recipients if you target by tag/attribute); an Active Sender ID; enough balance.

A campaign always launches from a template — you cannot send bulk SMS with raw inline text. Marketing campaigns additionally require the template text to be pre-approved; coordinate it with your account manager before launch.

Steps

1. Check readiness

curl https://client.routeon.io/api/v1/channels    -H "X-API-Key: <API_KEY>"
curl https://client.routeon.io/api/v1/senders     -H "X-API-Key: <API_KEY>"
curl https://client.routeon.io/api/v1/balance     -H "X-API-Key: <API_KEY>"

Confirm SMS (channel: 1) is available, your Sender ID shows status: 2 (Active), and the balance is sufficient.

2. (Optional) Import contacts

Only needed if you target the audience by tags/attributes rather than an explicit number list.

curl -X POST https://client.routeon.io/api/v1/recipient/recipients 
  -H "X-API-Key: <API_KEY>" -H "Content-Type: application/json" 
  -d '{
    "recipients": [
      { "name": "Alice", "phoneNumber": "48732231255", "tags": ["demo"], "attributes": { "name": "Alice" } }
    ],
    "tag": "demo",
    "type": "ENRICH"
  }'

3. Create an SMS template

curl -X POST https://client.routeon.io/api/v1/broadcast/templates 
  -H "X-API-Key: <API_KEY>" -H "Content-Type: application/json" 
  -d '{
    "name": "Demo SMS template",
    "description": "Welcome message",
    "extraRecipientList": [], "filterList": [], "tags": [],
    "contentType": 1,
    "content": {
      "flowSteps": [{
        "channelType": 1,
        "senderId": "Routeon",
        "contentPattern": "Hello {{attribute.name}}, this is a demo.",
        "deliveryCondition": "DELIVERY_SUCCESS",
        "timeout": 172800
      }]
    }
  }'

Use {{attribute.name}} placeholders to personalize from contact attributes.

4. Get the template id

curl "https://client.routeon.io/api/v1/broadcast/templates?limit=10&offset=0" 
  -H "X-API-Key: <API_KEY>"

Take the numeric id of the template you just created.

5. Launch the campaign

curl -X POST https://client.routeon.io/api/v1/broadcast/broadcasts 
  -H "X-API-Key: <API_KEY>" -H "Content-Type: application/json" 
  -d '{
    "templateId": 123,
    "launchTime": "",
    "webhook": "https://your.app/hooks/routeon",
    "recipientsList": [ { "phoneNumber": "905063565285" } ]
  }'

launchTime: empty string = send now; an ISO-8601 timestamp = schedule for later. Instead of recipientsList, you can rely on the tags/filters defined on the template.

Verify

A successful launch returns HTTP 200/201 (the body may be empty). Track progress through the campaign status webhook — one event per state change:

CREATED → STARTED → FINISHED (or FAILED / CANCELED)

{ "status": "FINISHED", "webhook": "https://your.app/hooks/routeon", "broadcastId": 12345, "message": null }

For per-recipient delivery detail, use the per-message delivery tracking — the campaign webhook is campaign-level only.

Common failures

Symptom	Cause	Fix
FAILED, message "…rejected by moderation"	Template text not approved for the destination	Get the campaign text approved via your account manager
401	Key missing the Broadcasts scope	Use a key with the Broadcasts scope
REJECTD on recipients	Sender ID not Active, or destination closed for your account	Check GET /senders (status 2) and confirm the route with your manager
Nothing sends	Insufficient balance	Top up (see balance)
No status events	No webhook resolved	Set webhook in the request or on the key; otherwise reconcile via GET /edrs