Skip to main content

​
Messaging API

Send messages on any supported channel, retrieve delivery status, retry failed sends, and manage reusable templates. Base path: /v1/messages

​
Send SMS

POST /v1/messages/sms Send an SMS message to a single recipient.
​
to
string
required
Recipient phone number in E.164 format (e.g., +14155552671)
​
body
string
required
The text content of the SMS (max 1600 characters; automatically segmented)
​
webhook_url
string
URL to receive delivery status callbacks for this message
​
metadata
object
Arbitrary key-value pairs attached to the message for your reference
curl -X POST https://orbit-api.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "body": "Your verification code is 123456",
    "webhook_url": "https://example.com/webhooks/sms",
    "metadata": { "campaign": "onboarding" }
  }'

{
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "to": "+14155552671",
    "status": "queued",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Send WhatsApp Message

POST /v1/messages/whatsapp Send a WhatsApp message — free-form text, a pre-approved template, or media.
​
to
string
required
Recipient phone number in E.164 format
​
text
object
Free-form text message object
​
template
object
Pre-approved WhatsApp template (use instead of text for business-initiated conversations)
​
media
object
Media attachment
​
metadata
object
Arbitrary key-value pairs attached to the message
curl -X POST https://orbit-api.devotel.io/api/v1/messages/whatsapp \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+905551234567",
    "text": { "body": "Hello from Orbit!" }
  }'

{
  "data": {
    "message_id": "msg_wa_456",
    "channel": "whatsapp",
    "to": "+905551234567",
    "status": "queued",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_abc456",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Send Email

POST /v1/messages/email Send a transactional email.
​
to
string | string[]
required
Recipient email address or array of addresses
​
subject
string
required
Email subject line
​
html
string
HTML body of the email (provide html or text, or both)
​
text
string
Plain-text body of the email
​
metadata
object
Arbitrary key-value pairs attached to the message
curl -X POST https://orbit-api.devotel.io/api/v1/messages/email \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "user@example.com",
    "subject": "Welcome to Orbit",
    "html": "<h1>Welcome!</h1><p>Thanks for signing up.</p>"
  }'

{
  "data": {
    "message_id": "msg_em_789",
    "channel": "email",
    "to": "user@example.com",
    "status": "queued",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_em_101",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Send RCS / Viber Message

POST /v1/messages/rcs | POST /v1/messages/viber Send a message on the RCS or Viber channel. Both use the same generic payload.
​
to
string
required
Recipient phone number in E.164 format
​
body
string
required
Message text content
​
metadata
object
Arbitrary key-value pairs attached to the message
curl -X POST https://orbit-api.devotel.io/api/v1/messages/rcs \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "body": "Your order has shipped!"
  }'

{
  "data": {
    "message_id": "msg_rcs_321",
    "channel": "rcs",
    "to": "+14155552671",
    "status": "queued",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_rcs_555",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
List Messages

GET /v1/messages Retrieve a paginated list of sent messages with optional filters.
​
cursor
string
Cursor for pagination (returned in previous response)
​
limit
integer
default:"20"
Number of results per page (max 100)
​
channel
string
Filter by channel: sms, whatsapp, rcs, viber, email
​
status
string
Filter by status: queued, sent, delivered, failed, read
​
to
string
Filter by recipient (exact match)
curl "https://orbit-api.devotel.io/api/v1/messages?channel=sms&status=delivered&limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "message_id": "msg_001",
      "channel": "sms",
      "to": "+14155552671",
      "status": "delivered",
      "created_at": "2026-03-08T11:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_list_001",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_msg_abc",
      "has_more": true,
      "total": 1542
    }
  }
}

​
Get Message

GET /v1/messages/{id} Retrieve details of a single message, including delivery status and timestamps.
​
id
string
required
Message ID (e.g., msg_abc123)
curl https://orbit-api.devotel.io/api/v1/messages/msg_abc123 \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "to": "+14155552671",
    "body": "Your verification code is 123456",
    "status": "delivered",
    "created_at": "2026-03-08T12:00:00Z",
    "delivered_at": "2026-03-08T12:00:03Z"
  },
  "meta": {
    "request_id": "req_get_001",
    "timestamp": "2026-03-08T12:01:00Z"
  }
}

​
Retry Message

POST /v1/messages/{id}/retry Re-send a message that previously failed. The original message parameters are reused.
​
id
string
required
ID of the failed message to retry
curl -X POST https://orbit-api.devotel.io/api/v1/messages/msg_fail_001/retry \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "message_id": "msg_retry_002",
    "original_message_id": "msg_fail_001",
    "status": "queued",
    "created_at": "2026-03-08T12:05:00Z"
  },
  "meta": {
    "request_id": "req_retry_001",
    "timestamp": "2026-03-08T12:05:00Z"
  }
}

​
Templates

​
List Templates

GET /v1/messages/templates Retrieve all message templates with cursor-based pagination.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
curl "https://orbit-api.devotel.io/api/v1/messages/templates?limit=10" \
  -H "X-API-Key: dv_live_sk_your_key_here"

​
Create Template

POST /v1/messages/templates Create a new message template for a given channel.
​
channel
string
required
Channel the template is for: sms, whatsapp, rcs, viber, email
​
name
string
required
Template name (unique per channel)
​
content
string
required
Template body content — use {{variable_name}} for dynamic placeholders
​
category
string
Template category (e.g., marketing, transactional, otp)
​
language
string
Language code (e.g., en, tr, ar)
​
variables
array
List of variable definitions used in the template content
​
status
string
Initial status: draft or pending_approval
curl -X POST https://orbit-api.devotel.io/api/v1/messages/templates \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "name": "order_confirmation",
    "content": "Hi {{customer_name}}, your order #{{order_id}} has been confirmed.",
    "category": "transactional",
    "language": "en"
  }'

{
  "data": {
    "id": "tpl_abc123",
    "channel": "whatsapp",
    "name": "order_confirmation",
    "content": "Hi {{customer_name}}, your order #{{order_id}} has been confirmed.",
    "category": "transactional",
    "language": "en",
    "status": "pending_approval",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_tpl_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
Delete Template

DELETE /v1/messages/templates/{id} Permanently delete a message template.
​
id
string
required
Template ID
Response: 204 No Content