​

SMS task recipes: batch, webhook, or dashboard

​

1. Decision matrix — which path wins

​

2. Batch path — recipient acceptance and the API contract

• Paste E.164 numbers separated by newlines, commas, or semicolons. Whitespace, dashes, and parentheses are stripped before validation.
• Upload a CSV (≤25 MB, one phone column). The phone column is located by header name — phone, phone_number, to, number, mobile, telephone, or tel are recognized; a header row that looks like a literal label is skipped, and E.164-shaped first values are treated as data rows.
• Per-row messages. If the CSV carries a message, body, text, content, sms, or sms_body header, the wizard switches to per-row mode: every row brings its own body and the compose step is skipped. Without such a header, a shared template with {{variable}} placeholders applies to every recipient.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/batch" \
  -H "X-API-Key: dv_live_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "recipients": [
      { "to": "+14155550001", "body": "Hi Alex, your pickup is ready." },
      { "to": "+447718590043", "body": "Hi Sam, your pickup is ready." }
    ],
    "from": "+15552341860",
    "scheduled_at": "2026-09-01T14:30:00Z",
    "webhook_url": "https://yourapp.com/webhooks/orbit"
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// Batch sends go to the canonical route POST /api/v1/messages/batch —
// reach it through the generic request helper, which attaches the API
// key, retries 429/5xx, and returns the parsed envelope.
const res = await orbit.request<{
  data: {
    batch_id: string;
    results: Array<{
      message_id: string;
      to: string;
      status: "sent" | "queued" | "scheduled" | "delivered" | "failed";
      error_code?: string;
      error_message?: string;
    }>;
    summary: {
      total: number;
      succeeded: number;
      failed: number;
      scheduled: number;
    };
  };
}>("POST", "/messages/batch", {
  data: {
    channel: "sms",
    recipients: [
      { to: "+14155550001", body: "Hi Alex, your pickup is ready." },
      { to: "+447718590043", body: "Hi Sam, your pickup is ready." },
    ],
    from: "+15552341860",
    scheduled_at: "2026-09-01T14:30:00Z",
    webhook_url: "https://yourapp.com/webhooks/orbit",
  },
});

{
  "data": {
    "batch_id": "batch_3f9k2m7q8x1v4z6a",
    "results": [
      {
        "message_id": "msg_8w5r2p9n4q7j3k6d",
        "to": "+14155550001",
        "status": "sent"
      },
      {
        "message_id": "msg_2x7p4q8n5r1k3j9d",
        "to": "+447718590043",
        "status": "sent"
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 2,
      "failed": 0,
      "scheduled": 0
    }
  },
  "meta": {
    "request_id": "req_batch_sms_01",
    "timestamp": "2026-09-01T14:29:58Z"
  }
}

• Response shape. HTTP 200 when every recipient is accepted; HTTP 207 (Multi-Status) when any recipient failed. The body carries batch_id, a per-recipient results[] with message_id, to, status (sent / queued / scheduled / delivered / failed), error_code, and error_message, plus a summary with succeeded / failed / scheduled totals. Treat 207 as a partial success — read results[] row by row rather than retrying the whole payload.
• Limits. Up to 10,000 recipients per call (per-tenant cap). A per-request webhook_url receives this batch’s DLRs only; for a standing stream, register an endpoint as in the next section.
• Semantics. Success rows read submitted (carrier accepted), not delivered — DLRs arrive asynchronously and move each row to Delivered / Submitted (no receipt) / Failed in the SMS list.

​

Errors — partial success and the wallet gate

{
  "data": {
    "batch_id": "batch_3f9k2m7q8x1v4z6a",
    "results": [
      {
        "message_id": "msg_8w5r2p9n4q7j3k6d",
        "to": "+14155550001",
        "status": "sent"
      },
      {
        "message_id": "msg_2x7p4q8n5r1k3j9d",
        "to": "+13105551234",
        "status": "failed",
        "error_code": "SUPPRESSED",
        "error_message": "Recipient is on the suppression list"
      }
    ],
    "summary": {
      "total": 2,
      "succeeded": 1,
      "failed": 1,
      "scheduled": 0
    }
  },
  "meta": {
    "request_id": "req_batch_sms_02",
    "timestamp": "2026-09-01T14:30:02Z"
  }
}

• 207 is the per-recipient verdict. Read results[] row by row and only retry the failed rows — the succeeded rows already have message IDs, so re-sending the whole batch double-sends them.
• Wallet gate (402). Before any recipient row is attempted, Orbit checks the prepaid balance covers the channel floor price × recipient count. If the wallet is short, the request returns 402 with INSUFFICIENT_BALANCE and no batch is persisted — top up from Billing → Top up and re-send the same payload; no partial debit occurs because the check runs before any message row is inserted.

​

3. Webhook-consumer path — the delivery contract your server must survive

1. Verify HMAC before anything else. Read the raw request body, check the signature timestamp (reject anything older than 5 minutes), and compare X-Orbit-Signature (fall back to the legacy X-Devotel-Signature) with a timing-safe HMAC-SHA256 over t.body. The endpoint’s cleartext whsec_... secret is returned exactly once at registration — copy it then.
2. Dedupe before work. Delivery is at-least-once; retries re-deliver the same event id. Persist seen IDs (a table with INSERT ... ON CONFLICT DO NOTHING) for at least 7 days so replayed dead letters don’t double-process.
3. Ack fast. Return 2xx within the 30-second window and hand the payload to your own queue. A slow or failing handler burns retry budget on work your queue would survive.
4. Survive retries and dead letters. A non-2xx or timeout triggers exponential-backoff retries for roughly 4–5 hours, then the event lands in the dead letter queue, replayable from Webhooks > Failed Deliveries for 7 days.
5. Rotate secrets without downtime. During rotation Orbit dual-signs — X-Orbit-Signature with the new secret, X-Orbit-Signature-Next with the previous — so a verifier that checks both headers accepts either key through the grace window.

​

4. Dashboard campaign path — when to invest

​

5. Data-hygiene chain — before any path

• Import and migrate contacts — pick the import surface (CSV wizard, async jobs, CDP ingest, or platform connectors), dry-run, map consent, dedupe.
• Opt-out lists — honor STOP keywords and maintain opt-out entries at the right scope.
• Message suppression — keep a tenant-owned suppression list so blocked numbers are filtered at send time.
• DNC pre-flight scrub — scrub recipient lists against do-not-contact entries before launch.

​

6. Pre-flight gates — why this step is non-optional

​

7. Local compliance — sender identity per destination country

• Sender ID country matrix — which sender types (alphanumeric, numeric, short code, long number) each destination supports and what registration each requires.
• US traffic: complete 10DLC registration before sending from a US long number; keep 10DLC rejections and re-vet open for campaign-review rejections. Toll-free verification covers US toll-free numbers instead.

​

8. After the first send — monitor and inspect

• Delivery log — search every delivery by message ID, provider reference, recipient, or sender and work a result row to its answer.
• Insights: deliverability — read the consolidated dashboard across channels to spot degradation before it lands in complaint tickets.
• Smart route preview — call POST /messages/route-preview to see which channel the router picks, why, and what it costs when the selected channel underperforms or the destination is better served by WhatsApp or RCS.

​

9. Troubleshooting — the common misreads

• “Delivered batch shows zero events.” The batch wizard and POST /messages/batch send but do not register an endpoint for you. Register one (Build a durable webhook consumer) or pass a per-batch webhook_url, and confirm it acks within its timeout before re-sending test traffic.
• “Blocked at a gate” reads as “provider rejected.” A gate is a tenant-owned admission check (wallet, quiet hours, suppression, frequency cap). The pre-flight checklist shows the admission order; count blocked rows after launch in the same guide.
• “Deliverability dashboard is clean but recipients say nothing arrived.” DLRs are per-recipient; check the Delivery log for the specific recipient’s status rather than the aggregate window.
• “The legislation oddly prohibits alphanumeric senders.” That is the destination, not a platform bug — confirm from the Sender ID country matrix and pick a compliant sender type per country.
• “US recipients flagged as blocked despite clean registration.” Check brand/campaign review status in 10DLC rejections and re-vet, not the aggregate dashboards.
• “CSV upload rejects the whole file.” The phone column must use a recognized header (phone, phone_number, to, number, mobile, telephone, tel) and each row must be a complete E.164 number — a message/body/text column switches the wizard into per-row mode, where a shared compose body no longer applies.

​

See also

• Batch SMS — the full wizard walkthrough and POST /messages/batch reference.
• Build a durable webhook consumer — the working receiver, dedupe store, and rotation flow.
• Send a campaign end-to-end — the full campaign lifecycle.
• Messaging services console — bundle sender pool, opt-out list, and inbound webhook under one id when compliance or routing needs a dedicated pool per region or use case.
• SMS sending services — the service-attachment model behind that console.