Campaigns API

Build and manage messaging campaigns across all channels. Create drafts, schedule delivery, monitor progress in real time, and retrieve aggregate analytics. Base path: /v1/campaigns

Create Campaign

POST /v1/campaigns Create a new campaign in draft status.

name

string

required

Campaign name

channel

string

required

Delivery channel: sms, whatsapp, rcs, viber, email

segment_id

string

Target segment ID — all contacts in this segment will receive the campaign

list_id

string

Target list ID (alternative to segment_id)

template_id

string

Message template to use

body

string

Inline message body (alternative to template_id)

scheduled_at

string

ISO 8601 timestamp for scheduled delivery (omit for manual send)

ab_test

object

A/B test configuration

Show child attributes

ab_test.enabled

boolean

Enable A/B testing

ab_test.variants

array

Array of message variants with split percentages

cURL

curl -X POST "https://orbit-api.devotel.io/api/v1/campaigns" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Spring Promo 2026",
  "channel": "sms",
  "segment_id": "seg_abc123",
  "body": "Hi {{first_name}}, enjoy 20% off this spring!",
  "scheduled_at": "2026-03-15T09:00:00Z"
}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

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

const res = await fetch('https://orbit-api.devotel.io/api/v1/campaigns', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "name": "Spring Promo 2026",
  "channel": "sms",
  "segment_id": "seg_abc123",
  "body": "Hi {{first_name}}, enjoy 20% off this spring!",
  "scheduled_at": "2026-03-15T09:00:00Z"
}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://orbit-api.devotel.io/api/v1/campaigns", headers=headers, json={
  "name": "Spring Promo 2026",
  "channel": "sms",
  "segment_id": "seg_abc123",
  "body": "Hi {{first_name}}, enjoy 20% off this spring!",
  "scheduled_at": "2026-03-15T09:00:00Z"
})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://orbit-api.devotel.io/api/v1/campaigns", bytes.NewBuffer([]byte(`{
  "name": "Spring Promo 2026",
  "channel": "sms",
  "segment_id": "seg_abc123",
  "body": "Hi {{first_name}}, enjoy 20% off this spring!",
  "scheduled_at": "2026-03-15T09:00:00Z"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://orbit-api.devotel.io/api/v1/campaigns')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "name": "Spring Promo 2026",
  "channel": "sms",
  "segment_id": "seg_abc123",
  "body": "Hi {{first_name}}, enjoy 20% off this spring!",
  "scheduled_at": "2026-03-15T09:00:00Z"
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://orbit-api.devotel.io/api/v1/campaigns');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{
  "name": "Spring Promo 2026",
  "channel": "sms",
  "segment_id": "seg_abc123",
  "body": "Hi {{first_name}}, enjoy 20% off this spring!",
  "scheduled_at": "2026-03-15T09:00:00Z"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "cmp_abc123",
    "name": "Spring Promo 2026",
    "channel": "sms",
    "status": "draft",
    "segment_id": "seg_abc123",
    "scheduled_at": "2026-03-15T09:00:00Z",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_cmp_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

List Campaigns

GET /v1/campaigns Retrieve campaigns with search, status, and channel filtering.

cursor

string

Cursor for pagination

limit

integer

default:"20"

Number of results per page (max 100)

string

Search by campaign name

status

string

Filter by status: draft, scheduled, sending, paused, completed, cancelled

channel

string

Filter by channel: sms, whatsapp, rcs, viber, email

Get Campaign

GET /v1/campaigns/{id} Retrieve a single campaign with full details and delivery progress.

string

required

Campaign ID (e.g., cmp_abc123)

Update Campaign

PUT /v1/campaigns/{id} Update a campaign’s configuration. Only campaigns in draft or scheduled status can be updated.

string

required

Campaign ID

name

string

Updated campaign name

body

string

Updated message body

scheduled_at

string

Updated schedule time (ISO 8601)

Delete Campaign

DELETE /v1/campaigns/{id} Delete a campaign. Only campaigns in draft status can be deleted.

string

required

Campaign ID

Response: 204 No Content

Send Campaign

POST /v1/campaigns/{id}/send Start sending a campaign immediately. Transitions the campaign from draft or scheduled to sending.

string

required

Campaign ID

cURL

curl -X POST "https://orbit-api.devotel.io/api/v1/campaigns/cmp_abc123/send" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

import { Orbit } from '@devotel/orbit-sdk'

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

const res = await fetch('https://orbit-api.devotel.io/api/v1/campaigns/cmp_abc123/send', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
headers["Content-Type"] = "application/json"
r = requests.post("https://orbit-api.devotel.io/api/v1/campaigns/cmp_abc123/send", headers=headers, json={})
print(r.json())

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://orbit-api.devotel.io/api/v1/campaigns/cmp_abc123/send", bytes.NewBuffer([]byte(`{}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://orbit-api.devotel.io/api/v1/campaigns/cmp_abc123/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://orbit-api.devotel.io/api/v1/campaigns/cmp_abc123/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, <<<JSON
{}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "cmp_abc123",
    "status": "sending",
    "started_at": "2026-03-08T12:10:00Z"
  },
  "meta": {
    "request_id": "req_send_001",
    "timestamp": "2026-03-08T12:10:00Z"
  }
}

Pause Campaign

POST /v1/campaigns/{id}/pause Pause a campaign that is currently sending. Remaining messages are held in queue.

string

required

Campaign ID

{
  "data": {
    "id": "cmp_abc123",
    "status": "paused",
    "paused_at": "2026-03-08T12:15:00Z"
  },
  "meta": {
    "request_id": "req_pause_001",
    "timestamp": "2026-03-08T12:15:00Z"
  }
}

Resume Campaign

POST /v1/campaigns/{id}/resume Resume a paused campaign. Delivery continues from where it stopped.

string

required

Campaign ID

Campaign Statistics

GET /v1/campaigns/stats Retrieve aggregate campaign statistics for your account.

{
  "data": {
    "total_campaigns": 47,
    "active_campaigns": 3,
    "total_messages_sent": 125430,
    "total_delivered": 121890,
    "total_failed": 1240,
    "delivery_rate": 0.971,
    "channels": {
      "sms": { "sent": 80000, "delivered": 78500 },
      "whatsapp": { "sent": 30000, "delivered": 29200 },
      "email": { "sent": 15430, "delivered": 14190 }
    }
  },
  "meta": {
    "request_id": "req_stats_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

Documentation Index

​Campaigns API

​Create Campaign

​List Campaigns

​Get Campaign

​Update Campaign

​Delete Campaign

​Send Campaign

​Pause Campaign

​Resume Campaign

​Campaign Statistics

Campaigns API

Create Campaign

List Campaigns

Get Campaign

Update Campaign

Delete Campaign

Send Campaign

Pause Campaign

Resume Campaign

Campaign Statistics