​

Send a campaign end-to-end

​

1. Prerequisites

• An API key with the campaigns:write scope. Every read below (audience preview, dry-run, stats) also accepts campaigns:read, but launch actions require write. Create or edit keys in the dashboard under Settings → API keys.
• Node SDK (optional). npm install @devotel-orbit/node if you prefer the SDK tabs over cURL.
• A sending identity for your channel. For SMS/MMS that means a number or sender pool with the right registrations (US A2P requires 10DLC); for WhatsApp, a connected WABA; for email, a verified sender domain.
• A sanctioned audience source. A contact list, a live segment, a CSV of recipient addresses, an external CRM audience (HubSpot list / Salesforce report), or a hand-picked set of contact ids. Audiences must come from opted-in recipients — suppression and unsubscribe handling is enforced at send time, not left to the sender.

​

2. Create the draft campaign

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail promo — summer sale",
    "type": "blast",
    "channel": "sms",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "Hi {{first_name}}, early access to our summer sale starts now: 25% off through Sunday. Reply STOP to opt out.",
    "send_time_optimization": "fixed"
  }'

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

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

const campaign = await orbit.campaigns.create({
  name: "Retail promo — summer sale",
  channel: "sms",
  message_template:
    "Hi {{first_name}}, early access to our summer sale starts now: 25% off through Sunday. Reply STOP to opt out.",
});

​

3. Attach and verify the audience

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "channel": "sms"
  }'

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

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

// No typed helper wraps this endpoint — the SDK index
// ([/sdks](/sdks#node)) routes uncovered endpoints through
// the generic `request()` escape hatch.
const preview = await orbit.request("POST", "/campaigns/audience/preview", {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  channel: "sms",
});

​

4. Personalization and locale

• Tokens are preserved verbatim across the translation.
• The single opt-out instruction stays exactly once (carrier requirement).

​

5. Pre-flight: run the dry-run

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY"

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

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

const report = await orbit.request(
  "POST",
  `/campaigns/${"cmp_abc123"}/dry-run`,
);
// Same escape hatch as the audience preview above — no body needed.

• audience.total_in_audience — gross matching count.
• audience.suppressed / opted_out / unreachable — net-projection cohorts (suppression list, per-channel opt-outs, missing channel address).
• audience.held_out — recipients carved into the incrementality control cohort if variables.campaign_holdout_percent is set; excluded from delivery.
• audience.deliverable — the exact net count the launch will attempt.
• cost.unit_price_cents / cost.total_cents — priced through the same resolver the send path uses, so the number matches the wallet deduction within rounding.
• cost.balance_cents / cost.sufficient — wallet check; a green dry-run implies a green launch balance gate.
• quiet_hours.skipped_estimate and quiet_hours.window — projected skip ratio from recipient-local quiet hours, plus the resolved window being evaluated.
• channel_waterfall — the primary channel and its cross-channel fallback shape, so you can verify RCS → SMS (or whatever chain you set) before pressing send.
• warnings[] — non-blocking issues (no registered provider for the channel, quiet hours fully closing the window, …) rendered separately from hard failures.

• Approvals. If your org requires a supervisor sign-off, the launch (POST /campaigns/:id/send) returns a pending-approval state instead of sending; the approver queue lives at GET /campaigns/approvals/pending, and org defaults at GET/PUT /campaigns/approvals/settings.
• Provider readiness. The dry-run checks list hygiene and provider registration implicitly through its warnings — a channel with no configured provider shows up there instead of failing at send.

​

6. Launch and choose the send shape

• Throttle. throttle_rate (msgs/sec) caps the send pace — the platform default is 50 msg/s; an explicit 0 also means default.
• Smart send. send_time_optimization: "recipient-optimal" schedules each recipient at their next best-time window from engagement profiles, and spreads delivery across the next 24h. Preview it first with POST /campaigns/:id/preview-smart-send, which returns per-contact recommended times plus a next_best_channel hint for the sample. To measure whether the timing itself is paying off, opt into a per-recipient hold-out cohort with variables.smart_send_holdout_pct — see step 7.
• Channel preview. If the campaign’s channel is still open, validate it against a sample of recipients with POST /messages/route-preview — the smart router’s recommendation, fallback chain, per-message cost, and engagement score, with nothing sent. To arm that chain for the send (so a terminal failure cascades instead of stopping at the first channel), pass cascade_policy on the same request — the smart-send fallback chains guide covers the per-message policy shape. The smart route preview guide walks the endpoint and the send-pipeline pattern.
• Send window. send_window: { start_local_hour, end_local_hour } defers recipients whose local time falls outside the window — a positive per-recipient window, distinct from quiet hours (a negative filter).

​

7. Observe and measure

​

8. Subscribe to campaign webhooks

• campaign.created / campaign.updated / campaign.deleted
• campaign.started / campaign.paused / campaign.resumed / campaign.cancelled / campaign.completed
• campaign.drip_step.sent / campaign.drip_step.completed / campaign.drip.completed

​

9. Troubleshooting

• Audience resolves to zero. Re-run the audience preview with a channel passed; the net projection tells you which cohort emptied it (all suppressed, all opted out, no reachable address). Fix the list or the channel address coverage, not the campaign.
• Dry-run shows red warnings. warnings[] entries are explicit — “no provider registered” means the channel has no configured sending identity; “quiet hours fully closed” means the resolved window rejects every local hour; “insufficient balance” means cost.sufficient: false. Clear the warning and re-run the dry-run.
• Launch returns 402 or a pending-approval shape. Balance check failed, or the approvals workflow is on — either top up the wallet or wait for POST /campaigns/approvals/:id/approve.
• Journey campaign stuck in paused. A campaign auto-pauses when it hits credit_cap_usd_cents or a broken drip step condition. Inspect GET /campaigns/:id/stats, clear the blocker, then POST /campaigns/:id/resume. Paused journeys keep their enrollment state; resuming continues where they stopped.
• Smart-send spreads deliveries too thin. recipient-optimal intentionally fans sends across 24h. If you need one batch, set send_time_optimization: "fixed" and use send_window if recipients span timezones.

​

Worked example: retail promo, draft to analytics

1. Create the draft.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retail promo — summer sale",
    "type": "blast",
    "channel": "sms",
    "audience_type": "list",
    "audience_id": "list_summerVIPs",
    "message_template": "Hi {{first_name}}, early access to our summer sale: 25% off through Sunday. Reply STOP to opt out.",
    "send_time_optimization": "recipient-optimal",
    "throttle_rate": 100,
    "variables": { "campaign_holdout_percent": 10 },
    "credit_cap_usd_cents": 50000
  }'

2. Preview the audience.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience_type": "list", "audience_id": "list_summerVIPs", "channel": "sms" }'

3. Dry-run it.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/dry-run" \
  -H "X-API-Key: $ORBIT_API_KEY"

4. Preview smart-send times (optional).

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/preview-smart-send" \
  -H "X-API-Key: $ORBIT_API_KEY"

5. Launch.

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/send" \
  -H "X-API-Key: $ORBIT_API_KEY"

6. Subscribe to lifecycle events (campaign.started, campaign.completed) and read stats as deliveries accumulate.
7. Measure. After the send completes:

curl "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/holdout-lift" \
  -H "X-API-Key: $ORBIT_API_KEY"
curl "https://api.orbit.devotel.io/api/v1/campaigns/cmp_abc123/roas" \
  -H "X-API-Key: $ORBIT_API_KEY"

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

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

const campaign = await orbit.campaigns.create({
  name: "Retail promo — summer sale",
  channel: "sms",
  message_template:
    "Hi {{first_name}}, early access to our summer sale: 25% off through Sunday. Reply STOP to opt out.",
});
const id = campaign.data.id;

// Attach the audience plus the fields the typed helper doesn't carry
// (holdout percent, spend cap, throttle) via a partial update.
await orbit.request("PUT", `/campaigns/${id}`, {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  type: "blast",
  send_time_optimization: "recipient-optimal",
  throttle_rate: 100,
  variables: { campaign_holdout_percent: 10 },
  credit_cap_usd_cents: 50000,
});

const preview = await orbit.request("POST", "/campaigns/audience/preview", {
  audience_type: "list",
  audience_id: "list_summerVIPs",
  channel: "sms",
});

const dryRun = await orbit.request("POST", `/campaigns/${id}/dry-run`);

// Launch — the typed helper auto-generates an idempotency key.
await orbit.campaigns.send(id);

const lift = await orbit.request("GET", `/campaigns/${id}/holdout-lift`);
const roas = await orbit.request("GET", `/campaigns/${id}/roas`);