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.

You can launch with raw text in payload (contentPattern). templateId is optional. Marketing text may still need approval before delivery.

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 or a past timestamp = send now; a future ISO-8601 timestamp = schedule. Instead of recipientsList, you can target tags or filters. To send without a saved template, put the text in payload as in Broadcast reference Example 4.

Verify

A successful launch returns HTTP 200 (the body may be empty). Statuses follow Alaris status_id: scheduled → in progress → completed (or failed / canceled / paused).

{ "status": "completed", "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