Frequency Caps API

Define rolling-window limits on how often a single contact can be messaged. Enforcement happens inside messages.service.sendMessage against Redis sorted sets — 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

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

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

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

Python (same call via the SDK’s escape hatch):

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

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

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.

Example — cap marketing SMS at 3 per day per contact

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

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"
  }
}

Transactional messages (OTPs, receipts) typically bypass caps via the category: "transactional" tag on the send request.

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: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "applies_to_categories": ["marketing"],
    "max_count": 3,
    "window_seconds": 86400
  }'

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: dv_live_sk_your_key_here"

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: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+14155552671",
    "body": "Flash sale — 30% off all summer sandals.",
    "metadata": { "category": "marketing" }
  }'

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).

{
  "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: dv_live_sk_your_key_here" \
  -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" }
  }'

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 — see the FE Automation → double-opt-in handshake.

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: dv_live_sk_your_key_here" \
  -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" }
    ]
  }'

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: dv_live_sk_your_key_here"

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

Example — cap marketing SMS at 3 per day per contact

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

​Example — cap marketing SMS at 3 per day per contact

​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

Example — cap marketing SMS at 3 per day per contact

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