Frequency Caps API

Define rolling-window limits on how often a single contact can be messaged. Enforcement happens inside the message send pipeline — sends that would exceed the cap return a FREQUENCY_CAP_EXCEEDED error and don’t dispatch. Base path: /api/v1/frequency-caps Authentication: API key (X-API-Key) or session JWT.

Method	Path	Purpose
`GET`	`/api/v1/frequency-caps/`	List rules
`POST`	`/api/v1/frequency-caps/`	Create a rule
`GET`	`/api/v1/frequency-caps/{id}`	Get a rule
`PATCH`	`/api/v1/frequency-caps/{id}`	Update a rule
`DELETE`	`/api/v1/frequency-caps/{id}`	Delete a rule

Using the SDKs

Node uses the typed orbit.frequencyCaps.* helpers; Python reaches the same endpoints through the generic client.request() escape hatch; Go, Ruby, and PHP use plain HTTP clients (no SDK dependency) against the same endpoints:

curl "https://api.orbit.devotel.io/api/v1/frequency-caps" \
  -H "X-API-Key: $ORBIT_API_KEY"

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

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

const res = await orbit.frequencyCaps.list();

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/frequency-caps")

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/frequency-caps", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/frequency-caps')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

The Python SDK is core-scope — it wraps the 8 core resources (messaging, voice, contacts, campaigns, verify, numbers) and reaches everything else through the generic client.request() escape hatch above. See the Python SDK. Returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Create a rule

curl -X POST "https://api.orbit.devotel.io/api/v1/frequency-caps" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "applies_to_categories": ["marketing"],
    "max_count": 3,
    "window_seconds": 86400
  }'

const res = await orbit.frequencyCaps.create({
  channel: "sms",
  applies_to_categories: ["marketing"],
  max_count: 3,
  window_seconds: 86_400, // 1 day rolling window
});

res = client.request("POST", "/frequency-caps", json_body={
    "channel": "sms",
    "applies_to_categories": ["marketing"],
    "max_count": 3,
    "window_seconds": 86400,
})

package main

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

func main() {
	body := []byte(`{"channel":"sms","applies_to_categories":["marketing"],"max_count":3,"window_seconds":86400}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/frequency-caps", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status) // 201 Created
}

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/frequency-caps')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"channel":"sms","applies_to_categories":["marketing"],"max_count":3,"window_seconds":86400}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"channel":"sms","applies_to_categories":["marketing"],"max_count":3,"window_seconds":86400}');
echo curl_exec($ch);

201 Created — rule shape

{
  "data": {
    "id": "fcap_abc",
    "organization_id": "org_2fx…",
    "channel": "sms",
    "scope": "channel",
    "window_seconds": 86400,
    "max_count": 3,
    "applies_to_categories": ["marketing"],
    "enabled": true,
    "created_at": "2026-08-20T11:00:00Z",
    "updated_at": "2026-08-20T11:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:00:00Z"
  }
}

Omit channel and set scope: "global" to aggregate the recipient’s sends across every channel into one counter. applies_to_categories omitted (or null) means the cap counts every category.

List rules

curl "https://api.orbit.devotel.io/api/v1/frequency-caps" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.frequencyCaps.list();

// Or page through every rule with the async iterator:
for await (const rule of orbit.frequencyCaps.iter()) {
  console.log(rule.id, rule.channel, rule.max_count);
}

res = client.request("GET", "/frequency-caps")

package main

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

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/frequency-caps", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

uri = URI('https://api.orbit.devotel.io/api/v1/frequency-caps')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Get a rule

curl "https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.frequencyCaps.get("fcap_abc");

res = client.request("GET", "/frequency-caps/fcap_abc")

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

uri = URI('https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Update a rule

Send only the fields you want to change. Setting applies_to_categories: null clears the category restriction so the cap counts every category again.

curl -X PATCH "https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_count": 5 }'

const res = await orbit.frequencyCaps.update("fcap_abc", {
  max_count: 5,
});

res = client.request("PATCH", "/frequency-caps/fcap_abc", json_body={
    "max_count": 5,
})

func main() {
	body := []byte(`{"max_count":5}`)
	req, _ := http.NewRequest("PATCH", "https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

uri = URI('https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc')
req = Net::HTTP::Patch.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"max_count":5}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"max_count":5}');
echo curl_exec($ch);

Delete a rule

curl -X DELETE "https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc" \
  -H "X-API-Key: $ORBIT_API_KEY"

await orbit.frequencyCaps.delete("fcap_abc");

client.request("DELETE", "/frequency-caps/fcap_abc")

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status) // 204 No Content
}

uri = URI('https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc')
req = Net::HTTP::Delete.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.code # 204

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps/fcap_abc');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

Recipes — cookbook-style

Plan a marketing blast that respects a per-contact daily cap. This walks the full hand-shake: create the cap, confirm the opt-in state, send with category: "marketing", then handle the FREQUENCY_CAP_EXCEEDED shape the pipeline returns when the recipient has already received all their slots. Step 1 — Create a channel-scoped marketing SMS cap (3 per day)

curl -X POST "https://api.orbit.devotel.io/api/v1/frequency-caps" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "applies_to_categories": ["marketing"],
    "max_count": 3,
    "window_seconds": 86400
  }'

const res = await orbit.frequencyCaps.create({
  channel: "sms",
  applies_to_categories: ["marketing"],
  max_count: 3,
  window_seconds: 86_400,
});

res = client.request("POST", "/frequency-caps", json_body={
    "channel": "sms",
    "applies_to_categories": ["marketing"],
    "max_count": 3,
    "window_seconds": 86400,
})

func main() {
	body := []byte(`{"channel":"sms","applies_to_categories":["marketing"],"max_count":3,"window_seconds":86400}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/frequency-caps", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

uri = URI('https://api.orbit.devotel.io/api/v1/frequency-caps')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"channel":"sms","applies_to_categories":["marketing"],"max_count":3,"window_seconds":86400}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/frequency-caps');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"channel":"sms","applies_to_categories":["marketing"],"max_count":3,"window_seconds":86400}');
echo curl_exec($ch);

Step 2 — Check the recipient’s opt-in state (skip if your stack pre-checks this in the UI). GET /api/v1/contacts/{id}/channel-state returns every channel the contact can be reached on plus suppression flags; the sms.opted_out flag inside channel_preferences gates send eligibility.

curl "https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.contacts.channelState("con_abc");

res = client.request("GET", "/contacts/con_abc/channel-state")

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

200 OK — opt-in state confirmed

{
  "data": {
    "id": "con_abc",
    "sms": {
      "opted_out": false,
      "reachable": true
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:01:00Z"
  }
}

Step 3 — Send with category="marketing" so the cap fires for the marketing traffic you intended it to

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/send" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+14155552671",
    "body": "Flash sale — 30% off all summer sandals.",
    "metadata": { "category": "marketing" }
  }'

const res = await orbit.messages.send({
  channel: "sms",
  to: "+14155552671",
  body: "Flash sale — 30% off all summer sandals.",
  metadata: { category: "marketing" },
});

res = client.request("POST", "/messages/send", json_body={
    "channel": "sms",
    "to": "+14155552671",
    "body": "Flash sale — 30% off all summer sandals.",
    "metadata": {"category": "marketing"},
})

func main() {
	body := []byte(`{"channel":"sms","to":"+14155552671","body":"Flash sale — 30% off all summer sandals.","metadata":{"category":"marketing"}}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/send", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

uri = URI('https://api.orbit.devotel.io/api/v1/messages/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"channel":"sms","to":"+14155552671","body":"Flash sale — 30% off all summer sandals.","metadata":{"category":"marketing"}}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"channel":"sms","to":"+14155552671","body":"Flash sale — 30% off all summer sandals.","metadata":{"category":"marketing"}}');
echo curl_exec($ch);

Step 4 — On cap overflow the send is rejected with 429 FREQUENCY_CAP_EXCEEDED. Your app should back off and retry only after retry_after_seconds (uses the oldest entry’s expiry to compute the next window). Each language surfaces the labelled envelope its own way:

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/send" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+14155552671",
    "body": "Flash sale — 30% off all summer sandals.",
    "metadata": { "category": "marketing" }
  }'
# → 429 {"error":{"code":"FREQUENCY_CAP_EXCEEDED", ... }}

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

try {
  await orbit.messages.send({
    channel: "sms",
    to: "+14155552671",
    body: "Flash sale — 30% off all summer sandals.",
    metadata: { category: "marketing" },
  });
} catch (err) {
  if (err instanceof OrbitApiError && err.code === "FREQUENCY_CAP_EXCEEDED") {
    const wait = (err.details as { retry_after_seconds?: number }).retry_after_seconds;
    // honour retry_after_seconds before re-queueing the send
  }
  throw err;
}

from orbit_sdk import OrbitRateLimitError

try:
    res = client.request("POST", "/messages/send", json_body={
        "channel": "sms",
        "to": "+14155552671",
        "body": "Flash sale — 30% off all summer sandals.",
        "metadata": {"category": "marketing"},
    })
except OrbitRateLimitError as err:
    if err.code == "FREQUENCY_CAP_EXCEEDED":
        wait = (err.details or {}).get("retry_after_seconds")  # honour before re-queueing

func main() {
	body := []byte(`{"channel":"sms","to":"+14155552671","body":"Flash sale — 30% off all summer sandals.","metadata":{"category":"marketing"}}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/send", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	if res.StatusCode == 429 {
		// FREQUENCY_CAP_EXCEEDED — read details.retry_after_seconds and back off
	}
}

uri = URI('https://api.orbit.devotel.io/api/v1/messages/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"channel":"sms","to":"+14155552671","body":"Flash sale — 30% off all summer sandals.","metadata":{"category":"marketing"}}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
if res.code == '429'
  # FREQUENCY_CAP_EXCEEDED — read details.retry_after_seconds and back off
end

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"channel":"sms","to":"+14155552671","body":"Flash sale — 30% off all summer sandals.","metadata":{"category":"marketing"}}');
curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) === 429) {
  // FREQUENCY_CAP_EXCEEDED — read details.retry_after_seconds and back off
}

The error envelope itself:

{
  "error": {
    "code": "FREQUENCY_CAP_EXCEEDED",
    "message": "Send blocked by a frequency-cap rule for this recipient and channel. Try again later or raise the cap in Settings → Frequency caps.",
    "status": 429,
    "details": {
      "channel": "sms",
      "window_seconds": 86400,
      "max_count": 3,
      "cap_id": "fcap_abc",
      "retry_after_seconds": 43200
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:05:00Z"
  }
}

Opt-out always wins over a cap. If the recipient’s channel_preferences.sms.opted_out === true (or the email is in the suppression list you pass to step 2), the send is rejected at the compliance gate before the frequency-cap check runs.

Recipe 2: transactional bypass

When you scope the cap to ["marketing"] you’re promising that OTPs and receipts ride free. Send a transactional message tagged category="transactional" and it skips the marketing cap entirely — it never claims a cap slot, it never gets blocked when a marketing recipient is over their limit.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/send" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+14155552671",
    "body": "Your Orbit verification code is 831447. It expires in 10 minutes.",
    "metadata": { "category": "transactional" }
  }'

const res = await orbit.messages.send({
  channel: "sms",
  to: "+14155552671",
  body: "Your Orbit verification code is 831447. It expires in 10 minutes.",
  metadata: { category: "transactional" },
});

res = client.request("POST", "/messages/send", json_body={
    "channel": "sms",
    "to": "+14155552671",
    "body": "Your Orbit verification code is 831447. It expires in 10 minutes.",
    "metadata": {"category": "transactional"},
})

func main() {
	body := []byte(`{"channel":"sms","to":"+14155552671","body":"Your Orbit verification code is 831447. It expires in 10 minutes.","metadata":{"category":"transactional"}}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/send", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

uri = URI('https://api.orbit.devotel.io/api/v1/messages/send')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"channel":"sms","to":"+14155552671","body":"Your Orbit verification code is 831447. It expires in 10 minutes.","metadata":{"category":"transactional"}}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/messages/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"channel":"sms","to":"+14155552671","body":"Your Orbit verification code is 831447. It expires in 10 minutes.","metadata":{"category":"transactional"}}');
echo curl_exec($ch);

200 OK — accepted (unrelated to the marketing cap’s state)

{
  "data": {
    "id": "msg_01ABCDEF",
    "channel": "sms",
    "to": "+14155552671",
    "status": "queued"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:06:00Z"
  }
}

Send suppression (content dedupe) and opt-out checks still apply — a re-delivered duplicate_content body inside the suppression window is skipped, and an email listed in email_suppressions blocks the email channel outright. Tagging category="transactional" shifts opt-in/off the cap’s cross-category exemption only.

A transactional send cannot bypass a cap set with applies_to_categories omitted (unspecified → every category, default included). To surface that gate-on, tag the send explicitly with category="transactional" and exclude transactional from applies_to_categories. Double-opt-in confirmation prompts ride their own out-of-band exemption.

Recipe 3: bulk on-call import — mass opt-out file, then verify

A support-evidence export or a paid-suppression vendor file arrives and 50 000 contacts need to be marked as opted_out on sms. Single POST /optouts calls would take hours. This recipe:

loads the file through POST /api/v1/contacts/optouts/bulk (up to 500 rows per call)
then verifies each row’s state with GET /api/v1/contacts/{id}/channel-state so a retry loop is idempotent

Step 1 — POST the bulk rows (chunk your CSV into ≤ 500-row payloads in your application code)

curl -X POST "https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "contact": "+14155552671", "channel": "sms", "reason": "vendor-suppression-file" },
      { "contact": "+14155552672", "channel": "sms", "reason": "vendor-suppression-file" },
      { "contact": "+14155552673", "channel": "sms", "reason": "vendor-suppression-file" }
    ]
  }'

// Bulk is an escape-hatch op — call the endpoint directly on the client:
const res = await orbit.request(
  "POST",
  "/contacts/optouts/bulk",
  {
    rows: [
      { contact: "+14155552671", channel: "sms", reason: "vendor-suppression-file" },
      { contact: "+14155552672", channel: "sms", reason: "vendor-suppression-file" },
      { contact: "+14155552673", channel: "sms", reason: "vendor-suppression-file" },
    ],
  },
);

res = client.request("POST", "/contacts/optouts/bulk", json_body={
    "rows": [
        {"contact": "+14155552671", "channel": "sms", "reason": "vendor-suppression-file"},
        {"contact": "+14155552672", "channel": "sms", "reason": "vendor-suppression-file"},
        {"contact": "+14155552673", "channel": "sms", "reason": "vendor-suppression-file"},
    ],
})

func main() {
	body := []byte(`{"rows":[{"contact":"+14155552671","channel":"sms","reason":"vendor-suppression-file"},{"contact":"+14155552672","channel":"sms","reason":"vendor-suppression-file"},{"contact":"+14155552673","channel":"sms","reason":"vendor-suppression-file"}]}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk", bytes.NewBuffer(body))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status) // 207 Multi-Status
}

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = '{"rows":[{"contact":"+14155552671","channel":"sms","reason":"vendor-suppression-file"},{"contact":"+14155552672","channel":"sms","reason":"vendor-suppression-file"},{"contact":"+14155552673","channel":"sms","reason":"vendor-suppression-file"}]}'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
puts res.body

<?php
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/optouts/bulk');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'X-API-Key: ' . getenv('ORBIT_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"rows":[{"contact":"+14155552671","channel":"sms","reason":"vendor-suppression-file"},{"contact":"+14155552672","channel":"sms","reason":"vendor-suppression-file"},{"contact":"+14155552673","channel":"sms","reason":"vendor-suppression-file"}]}');
echo curl_exec($ch);

207 Multi-Status — each row’s status is succeeded (newly opted out), skipped (already opted out), or failed so the wizard can surface per-row errors without rolling back the whole batch.

{
  "data": {
    "total": 3,
    "succeeded": 2,
    "skipped": 1,
    "failed": 0,
    "results": [
      { "contact": "+14155552671", "channel": "sms", "ok": true, "status": "succeeded" },
      { "contact": "+14155552672", "channel": "sms", "ok": true, "status": "skipped" },
      { "contact": "+14155552673", "channel": "sms", "ok": true, "status": "succeeded" }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:10:00Z"
  }
}

Step 2 — Verify the opt-out landed on the channel. GET /api/v1/contacts/{id}/channel-state is the single source of truth across caps, opt-outs, and suppression lists, so an idempotent re-check reads sms.opted_out: true.

curl "https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state" \
  -H "X-API-Key: $ORBIT_API_KEY"

const res = await orbit.contacts.channelState("con_abc");

res = client.request("GET", "/contacts/con_abc/channel-state")

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

uri = URI('https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state')
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
$ch = curl_init('https://api.orbit.devotel.io/api/v1/contacts/con_abc/channel-state');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('ORBIT_API_KEY')]);
echo curl_exec($ch);

200 OK

{
  "data": {
    "id": "con_abc",
    "sms": {
      "opted_out": true,
      "reachable": false
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:11:00Z"
  }
}

For high-volume import flows past 500 rows, use the async CSV importer POST /api/v1/contacts/imports (results are polled via GET /api/v1/contacts/imports/{id} and POST /api/v1/contacts/imports/preview for a dry-run) — see Imports API.

Recipe errors

Scenario	HTTP	`error.code`
Marketing recipient, all cap slots consumed	`429`	`FREQUENCY_CAP_EXCEEDED`
Contact opted out of channel (compliance gate)	`400`	`OPTED_OUT` (send rejected, no retry)
Validation failure (cap shape, send shape)	`422`	`VALIDATION_ERROR`
API key lacks `messages:send` or caller has `viewer` role	`403`	`FORBIDDEN`

API Reference

All Endpoints

Frequency Caps API: per-contact rolling send limits

Frequency Caps API

Using the SDKs

Create a rule

List rules

Get a rule

Update a rule

Delete a rule

Recipes — cookbook-style

Recipe 2: transactional bypass

Recipe 3: bulk on-call import — mass opt-out file, then verify

Recipe errors

See also

​Frequency Caps API

​Using the SDKs

​Create a rule

​List rules

​Get a rule

​Update a rule

​Delete a rule

​Recipes — cookbook-style

​Recipe 1: consent-gated outbound SMS

​Recipe 2: transactional bypass

​Recipe 3: bulk on-call import — mass opt-out file, then verify

​Recipe errors

​See also

Frequency Caps API

Using the SDKs

Create a rule

List rules

Get a rule

Update a rule

Delete a rule

Recipes — cookbook-style

Recipe 1: consent-gated outbound SMS

Recipe 2: transactional bypass

Recipe 3: bulk on-call import — mass opt-out file, then verify

Recipe errors

See also