MessageSuppression API

MessageSuppression endpoints exposed by the Devotel CPaaS API Base path: /api/v1/message-suppression Endpoint count: 3

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

These five failures cover the suppression check (GET /api/v1/messagesuppression/check), in the pre-send path for every channel. Each block below is a full { error, meta } envelope as the API returns it, and the matrix at the bottom answers retry vs surface for the same five classes. For the platform-wide decision table these branches plug into, see the error handling guide.

401 — Unauthorized

  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "The API key is invalid, expired, or lacks the required scope.",
      "status": 401
    },
    "meta": {
      "request_id": "req_messagesa1",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 401 on this page is the bearer key failing before the route ran — it never means the resource is wrong. Rotate the key or re-mint the scoped token; retrying the same request changes nothing.

403 — Forbidden

  {
    "error": {
      "code": "FORBIDDEN",
      "message": "The key is valid but does not have the scope this operation requires.",
      "status": 403
    },
    "meta": {
      "request_id": "req_messagesa1f",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 403 means the key authenticated but the operation is gated by scope — check the key’s scopes on the developer page; a 403 is never a data-not-found shape.

422 — Schema

  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "The request failed input validation.",
      "status": 422,
      "details": { "field": "scope", "value": "ORG", "expected": "one of account, team, sender" }
    },
    "meta": {
      "request_id": "req_messagesb2",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

A 422 means the payload did not match the request schema — branch on error.details.field and resend with one of account, team, sender for scope instead of blind-retrying the same body.

429 — Rate

  {
    "error": {
      "code": "RATE_LIMITED",
      "message": "Too many requests in the current window.",
      "status": 429,
      "details": { "retry_after": 12 }
    },
    "meta": {
      "request_id": "req_messagesc3",
      "timestamp": "2026-09-03T12:00:00Z",
      "docs_url": "https://docs.orbit.devotel.io/errors/RATE_LIMITED"
    }
  }

The Retry-After header and error.details.retry_after are both set on every 429 — resend the SAME request after the lower of the two.

404 — Not found

  {
    "error": {
      "code": "SUPPRESSION_RULE_UNKNOWN",
      "message": "The referenced suppression rule does not exist for this tenant.",
      "status": 404,
      "details": { "rule_id": "rule_0192" }
    },
    "meta": {
      "request_id": "req_messagesd4",
      "timestamp": "2026-09-03T12:00:00Z"
    }
  }

List the rules first — a deleted id never resolves on retry.

60-second retry matrix

Class	Meaning	Branch response
401 `UNAUTHORIZED`	the bearer key itself fails	Surface. Rotate the key or re-mint the scoped token; do not retry the same request.
403 `FORBIDDEN`	the key lacks this operation’s scope	Surface. Fix the key’s scope set; a retry with the same key never heals it.
422 `VALIDATION_ERROR`	the payload does not match the schema	Fix, then resend intentionally. Branch on `error.details.field`; a blind retry repeats the same 422.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request body.
`SUPPRESSION_RULE_UNKNOWN` (404 not found)	List the rules first	Branch on `error.code`. A deleted id never resolves on retry.

Get the duplicate-message suppression policy

GET /api/v1/message-suppression

Returns the organization’s content-hash duplicate-message suppression policy — the opt-in guard that silently drops a send when the identical message body was already delivered to the same recipient on the same channel within the configured window. Use this to inspect the current window, channel restrictions, and category filter before updating or deleting the policy. Returns data: null when no policy has ever been configured for the organization.

string (enum: true|false)

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/message-suppression" \
  -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/message-suppression', {
  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/message-suppression", 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/message-suppression", 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/message-suppression')
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/message-suppression');
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": {
    "enabled": true,
    "window_seconds": 86400,
    "channels": [
      "sms",
      "email"
    ],
    "applies_to_categories": [
      "marketing",
      "promotional"
    ],
    "updated_at": "2026-08-28T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_9f4b2d8c1a7e",
    "timestamp": "2026-08-28T12:00:00.000Z"
  }
}

Create or update the duplicate-message suppression policy

PUT /api/v1/message-suppression

Upserts the organization’s single duplicate-message suppression policy. When a matching policy fires, an identical message body to the same recipient on the same channel is silently suppressed within window_seconds — the guard against two campaigns sending the same promo back-to-back. Omit channels (or pass null) to cover every outbound messaging channel, and omit applies_to_categories to cover every message category; restrict the category list to marketing copy so OTP and transactional resends are never suppressed. Body: window_seconds (3600–7776000), optional enabled (defaults true), and optional channels / applies_to_categories (null or omitted = every channel / every category). Requires owner, admin, or developer role.

string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

string (enum: true|false)

cURL

curl -X PUT "https://api.orbit.devotel.io/api/v1/message-suppression" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/message-suppression', {
  method: 'PUT',
  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.put("https://api.orbit.devotel.io/api/v1/message-suppression", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/message-suppression", 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://api.orbit.devotel.io/api/v1/message-suppression')
req = Net::HTTP::Put.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://api.orbit.devotel.io/api/v1/message-suppression');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
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": {
    "enabled": true,
    "window_seconds": 86400,
    "channels": [
      "sms",
      "email"
    ],
    "applies_to_categories": [
      "marketing",
      "promotional"
    ],
    "updated_at": "2026-08-28T12:00:00.000Z"
  },
  "meta": {
    "request_id": "req_9f4b2d8c1a7e",
    "timestamp": "2026-08-28T12:00:00.000Z"
  }
}

Delete the duplicate-message suppression policy

DELETE /api/v1/message-suppression

Removes the organization’s duplicate-message suppression policy. Deletion disables suppression immediately — identical messages are no longer dropped — while any per-content markers already recorded in the window expire with their TTL. Returns 204 No Content whether or not a policy existed (idempotent delete). Requires owner, admin, or developer role.

string (enum: true|false)

cURL

curl -X DELETE "https://api.orbit.devotel.io/api/v1/message-suppression" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

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/message-suppression', {
  method: 'DELETE',
  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.delete("https://api.orbit.devotel.io/api/v1/message-suppression", headers=headers, json={})
print(r.json())

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/message-suppression", 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://api.orbit.devotel.io/api/v1/message-suppression')
req = Net::HTTP::Delete.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://api.orbit.devotel.io/api/v1/message-suppression');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
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);

Response: 204 No Content

API Reference

All Endpoints

MessageSuppression API

MessageSuppression API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

404 — Not found

60-second retry matrix

Get the duplicate-message suppression policy

Create or update the duplicate-message suppression policy

Delete the duplicate-message suppression policy

​MessageSuppression API

​title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

​Errors worth branching on

​401 — Unauthorized

​403 — Forbidden

​422 — Schema

​429 — Rate

​404 — Not found

​60-second retry matrix

​Get the duplicate-message suppression policy

​Create or update the duplicate-message suppression policy

​Delete the duplicate-message suppression policy

MessageSuppression API

title: “Errors worth branching on” description: “Per-endpoint failure templates matching the envelope — what actually fires, what to retry, what to surface to the operator.”

Errors worth branching on

401 — Unauthorized

403 — Forbidden

422 — Schema

429 — Rate

404 — Not found

60-second retry matrix

Get the duplicate-message suppression policy

Create or update the duplicate-message suppression policy

Delete the duplicate-message suppression policy