Worked request and response samples

Correlated message-ID lookup — GET /api/v1/messages accepts ?message_ids=<id1,id2,...> (up to 100) as a cross-channel delivery log search. Each id is OR-matched against the internal id OR the provider-assigned external_id (e.g. a Twilio MessageSid, a WABA message id, a Resend email id), so the provider id you already hold resolves the same row. Combine with channel / from_date / to_date to narrow.For POST /messages/batch, the full pipeline model — persist-then-attempt invariants, per-tenant caps and the safety ceiling, and per-recipient outcome rows — is on the Batch-send model concept page.

string

Search DSL — fielded field:value clauses AND-ed together. Supported fields include message_id, external_id, status, channel, direction, from, to, body, created, updated, conversation_id, contact_id. message_id and external_id both look up the provider-side identifier (Jasmin/SMPP receipt ref, Meta wamid, Resend email id, jambonz CallSid, Telnyx fax id) from the provider console. String fields support * wildcards. Invalid syntax or unknown fields return 400. See the Search message history guide.

Copy a request as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit’s { error, meta } envelope. The chain a sender runs: send → poll → receive the delivery webhook.

1. Send an SMS

POST /api/v1/messages/sms

Request

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/sms" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+14155552671",
  "from": "+12125550100",
  "body": "Your pickup is ready at counter 4.",
  "webhook_url": "https://your-app.example/dlr"
}'

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/sms', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "to": "+14155552671",
  "from": "+12125550100",
  "body": "Your pickup is ready at counter 4.",
  "webhook_url": "https://your-app.example/dlr"
}),
})
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://api.orbit.devotel.io/api/v1/messages/sms", headers=headers, json={
  "to": "+14155552671",
  "from": "+12125550100",
  "body": "Your pickup is ready at counter 4.",
  "webhook_url": "https://your-app.example/dlr"
})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/sms", bytes.NewBuffer([]byte(`{
  "to": "+14155552671",
  "from": "+12125550100",
  "body": "Your pickup is ready at counter 4.",
  "webhook_url": "https://your-app.example/dlr"
}`)))
	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://api.orbit.devotel.io/api/v1/messages/sms')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  "to": "+14155552671",
  "from": "+12125550100",
  "body": "Your pickup is ready at counter 4.",
  "webhook_url": "https://your-app.example/dlr"
}.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://api.orbit.devotel.io/api/v1/messages/sms');
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
{
  "to": "+14155552671",
  "from": "+12125550100",
  "body": "Your pickup is ready at counter 4.",
  "webhook_url": "https://your-app.example/dlr"
}
JSON);
echo curl_exec($ch);

{
  "data": {
    "id": "msg_9e8d7c6b5a4f3021e5d6c7b8a1b2c3d4",
    "channel": "sms",
    "to": "+14155552671",
    "from": "+12125550100",
    "body": "Your pickup is ready at counter 4.",
    "status": "queued",
    "created_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_sms_send",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

The returned id is the handle you poll and that webhook deliveries reference. Sandbox sends terminate at test_sent instead of queued/provider states; when you authenticate with a sandbox key the meta block carries test_mode: true and the message row settles at test_sent:

string

queued on live sends; test_sent on sandbox/test-mode sends. Poll GET /api/v1/messages/{id} (below) for transitions.

2. Poll the message status

GET /api/v1/messages/{id}

Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/messages/{id}" \
  -H "X-API-Key: dv_live_sk_your_key_here" 

Node.js

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

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

const res = await fetch('https://api.orbit.devotel.io/api/v1/messages/{id}', {
  method: 'GET',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
  },
})
console.log(await res.json())

Python

import os, requests

headers = {"X-API-Key": os.environ["ORBIT_API_KEY"]}
r = requests.get("https://api.orbit.devotel.io/api/v1/messages/{id}", headers=headers)
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/messages/{id}", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	http.DefaultClient.Do(req)
}

Ruby

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/{id}')
req = Net::HTTP::Get.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']


res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

PHP

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/{id}');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),

]);

echo curl_exec($ch);

{
  "data": {
    "id": "msg_9e8d7c6b5a4f3021e5d6c7b8a1b2c3d4",
    "channel": "sms",
    "to": "+14155552671",
    "from": "+12125550100",
    "status": "delivered",
    "created_at": "2026-08-01T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_msg_get",
    "timestamp": "2026-08-01T12:00:04.000Z"
  }
}

Typical transition order: pending → queued → sent → delivered. Terminal failures land on failed / rejected / undelivered / expired. The full lifecycle, including every status the filter accepts, is on the status lifecycle page.

3. Delivery receipts via webhook

Terminal transitions also send a message.delivered / message.failed event to your webhook_url or subscribed endpoint. The delivery-receipt wire shape (envelope, signature headers, retry behaviour) is documented in Webhook event payloads — subscribe to message.delivered and message.failed rather than polling.

4. Send errors to handle

Invalid recipient → 422 INVALID_PHONE_NUMBER. The pre-send numbering-plan check rejects unrouteable destinations before a provider call:

422

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "status": 422,
    "message": "The destination number is not valid for its country numbering plan."
  },
  "meta": {
    "request_id": "req_sms_err",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

Empty wallet → 402 INSUFFICIENT_BALANCE. Top up your balance and resend:

402

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "status": 402,
    "message": "Insufficient balance. Add funds to your account to continue sending.",
    "details": { "balance_minor": 0 }
  },
  "meta": {
    "request_id": "req_sms_err2",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

5. Create a message template

POST /api/v1/messages/templates

The same request shape returns a created-record envelope on 201. Approval-required channels (WhatsApp, RCS, Kakao, Zalo) come back draft and move to pending on carrier submission; platform-only channels (SMS, email, Viber) land active and are immediately sendable. Full lifecycle on Outbound templates.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/templates" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "name": "order_confirm_v2",
    "language": "en",
    "content": "Hi {{first_name}}, your order {{order_id}} is confirmed."
  }'

{
  "data": {
    "id": "tmpl_02KA7QWXYZ",
    "channel": "sms",
    "name": "order_confirm_v2",
    "language": "en",
    "status": "active",
    "content": { "body": "Hi {{first_name}}, your order {{order_id}} is confirmed." },
    "created_at": "2026-09-05T10:12:44.000Z",
    "updated_at": "2026-09-05T10:12:44.000Z"
  },
  "meta": {
    "request_id": "req_tmpl_create",
    "timestamp": "2026-09-05T10:12:44.000Z"
  }
}

For the cross-channel author layer (Twilio Content API parity), group per-channel variants with a fallback order under one logical id:

POST /api/v1/messages/content-templates

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/content-templates" \
  -H "X-API-Key: dv_test_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "order_shipped_multichannel",
    "default_channel": "whatsapp",
    "fallback_chain": ["whatsapp", "sms"],
    "variants": {
      "whatsapp": { "body": "Hi {{1}}, order {{2}} just shipped." },
      "sms": { "body": "Hi {{1}}, order {{2}} shipped." }
    }
  }'

{
  "data": {
    "id": "ct_01J9Z8ABCDEF",
    "friendly_name": "order_shipped_multichannel",
    "default_channel": "whatsapp",
    "fallback_chain": ["whatsapp", "sms"],
    "status": "active",
    "created_at": "2026-09-05T10:15:03.000Z"
  },
  "meta": {
    "request_id": "req_ct_create",
    "timestamp": "2026-09-05T10:15:03.000Z"
  }
}

API Reference

All Endpoints

Worked request and response samples