Message Suppression API

Configure content-hash duplicate suppression: a send is silently skipped when the same message body already reached the same contact on the same channel inside a window you choose. This is the “two different campaigns fired the identical promo back-to-back” guard — distinct from frequency caps (which count send firings per contact) and opt-outs (which block a channel entirely). Enforcement happens inside the message send pipeline, before frequency capping, so a duplicate never burns a cap slot. A suppressed send reports as skipped (reason duplicate_content) rather than an error, so campaigns and batches keep moving. Base path: /api/v1/message-suppression Authentication: API key (X-API-Key) or session JWT. Reads require any role; the upsert and delete writes require owner, admin, or developer.

Method	Path	Purpose
`GET`	`/api/v1/message-suppression/`	Read the org’s policy (`null` when none is configured)
`PUT`	`/api/v1/message-suppression/`	Create or update the policy
`DELETE`	`/api/v1/message-suppression/`	Turn suppression off (delete the policy)

Node uses the typed orbit.messageSuppression.* helpers; Python reaches the endpoints through the generic client.request() escape hatch; Go, Ruby, and PHP use plain HTTP clients (no SDK dependency). Each operation carries the full sample group.

Get the policy

Returns the org’s single policy, or null when none has ever been configured.

curl "https://api.orbit.devotel.io/api/v1/message-suppression" \
  -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.messageSuppression.get();

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/message-suppression")

package main

import (
	"fmt"
	"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"))
	res, _ := http.DefaultClient.Do(req)
	fmt.Println(res.Status)
}

require 'net/http'

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

200 OK — no policy configured When suppression has never been turned on for the organization, data is null (not a 404 — the endpoint always exists).

{
  "data": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:00:00Z"
  }
}

200 OK — policy set Once a PUT has landed, GET returns the same shape the upsert echoes back.

{
  "data": {
    "enabled": true,
    "window_seconds": 86400,
    "channels": ["sms", "email"],
    "applies_to_categories": null,
    "updated_at": "2026-08-20T11:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:10:00Z"
  }
}

Create or update the policy

A PUT upserts the single policy: send the full body each time. A bare PUT with only window_seconds turns the policy on (enabled defaults to true).

curl -X PUT "https://api.orbit.devotel.io/api/v1/message-suppression" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"window_seconds":86400,"channels":["sms","email"]}'

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

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

await orbit.messageSuppression.upsert({
  window_seconds: 86_400, // skips within 24 hours of the first send
  channels: ["sms", "email"],
});

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

client.request("PUT", "/message-suppression", json_body={
    "window_seconds": 86400,
    "channels": ["sms", "email"],
})

package main

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

func main() {
	body := []byte(`{"window_seconds":86400,"channels":["sms","email"]}`)
	req, _ := http.NewRequest("PUT", "https://api.orbit.devotel.io/api/v1/message-suppression", 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)
}

require 'net/http'

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 = '{"window_seconds":86400,"channels":["sms","email"]}'
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/message-suppression');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
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, '{"window_seconds":86400,"channels":["sms","email"]}');
echo curl_exec($ch);

Delete the policy

Turns suppression off. The operation is idempotent — the endpoint returns 204 No Content whether or not a policy existed, so a cleanup pass can safely re-run.

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

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

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

await orbit.messageSuppression.delete();

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

client.request("DELETE", "/message-suppression")

package main

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

func main() {
	req, _ := http.NewRequest("DELETE", "https://api.orbit.devotel.io/api/v1/message-suppression", 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/message-suppression')
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/message-suppression');
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);

204 No Content — the policy is gone and the response body is empty, on the first DELETE and on every repeat. A follow-up GET returns the data: null envelope above. 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. Node returns the typed ApiResponse envelope. See the SDK index at SDK quickstart.

Policy shape

A single opt-in policy per organization.

Field	Type	Notes
`enabled`	`boolean`	Defaults to `true`. A bare `PUT` with a window turns the policy on.
`window_seconds`	`integer`	How long a delivered body is remembered. Bounds: `3600` (1 hour) … `7776000` (90 days).
`channels`	`string[] \| null`	`null` / omitted = every channel. A populated list restricts the policy to those channels (same channel set as frequency caps).
`applies_to_categories`	`string[] \| null`	`null` / omitted = every category. Populate with e.g. `["marketing"]` so one-time passcodes, receipts, and other transactional sends are never held back.
`updated_at`	`string`	Read-only ISO-8601 timestamp of the last change.

Example — dedupe marketing sends within 7 days

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 '{
    "enabled": true,
    "window_seconds": 604800,
    "channels": ["sms", "whatsapp"],
    "applies_to_categories": ["marketing"]
  }'

200 OK — the configured policy (consistent with GET)

{
  "data": {
    "enabled": true,
    "window_seconds": 604800,
    "channels": ["sms", "whatsapp"],
    "applies_to_categories": ["marketing"],
    "updated_at": "2026-08-20T11:00:00Z"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-20T11:00:00Z"
  }
}

Restricting applies_to_categories to marketing means OTP and transactional resends are never suppressed. Omit channels (or send null) to cover every messaging channel.

Suppression fails open: if no policy applies, or the backing store is briefly unavailable, the send is dispatched normally — a transient blip never silently swallows outbound traffic. Bodies are compared by SHA-256 of the whitespace-normalized text, so cosmetically-identical copy (reflowed spacing) collapses to the same marker while different case or wording does not.

Recipes — cookbook-style

Recipe 1: same body to the same recipient, twice inside the window

A marketing campaign fires; a rerun from a different campaign name, journey step, or operator action replays the same body. Suppression catches the second send before it consumes a slot.

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

200 OK — first send accepted

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

Re-send the same payload within the 7-day window and the pipeline returns a soft skip rather than a hard error — the batch keeps moving.

{
  "data": { "id": "msg_002", "status": "skipped", "reason": "duplicate_content", "channel": "sms", "to": "+14155552671" },
  "meta": { "request_id": "req_second", "timestamp": "2026-08-20T11:01:00Z" }
}

Your campaign batch exporter, webhook workers, and journey enqueues see status: "skipped" with either reason: "duplicate_content" (suppression) or reason: "frequency_capped" (inter-campaign cap skip, campaign sending) and can drop the row from the “true delivery” count.

Recipe 2: any channel blocked by opt-in (still respected)

Suppression is parallel to the opt-out gate, not instead of it. A duplicate_content skip only happens when the contact is otherwise eligible; if they’ve opted out of the channel, the compliance gate blocks the send outright (no skipped reason for compliance — the send is rejected at the front).

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

400 — opted out (suppression never runs if the opt-out gate rejects)

{
  "error": {
    "code": "OPTED_OUT",
    "message": "Recipient has opted out of this channel.",
    "status": 400
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-08-20T11:02:00Z" }
}

Restricting applies_to_categories: ["marketing"] in your PUT body keeps transactional re-sends (password resets, receipts, OTPs) outside suppression’s scope while marketing traffic is still deduped.

Recipe 3: bulk on-call import + poll-and-verify

For bulk suppression-file imports (an on-call policy download that should become organization-wide rule), do the write through POST /api/v1/contacts/optouts/bulk — suppression’s PUT is for dedupe policy; opt-outs are the per-contact block list. Pair it with a poll loop on the async contact importer when the row count exceeds a few hundred.

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": "oncall-suppression-file" } ] }'

Verify each row landed by polling GET /api/v1/contacts/imports/{id} (for async-import flows) or GET /api/v1/contacts/{id}/channel-state (synchronous verify) — sms.opted_out should be true on the response. Suppress-only-bulk has no separate endpoint; the policy is a single org-level object set via PUT. Use POST /contacts/optouts/bulk when the intent is “suppress this cohort on channel X” (per-contact block) and PUT /api/v1/message-suppression/ when the intent is “dedupe identical bodies within a window for everyone” (org policy). See the Opt-Outs API for the CSV import wizard endpoints.

Classify a message

POST /api/v1/messages/classify scores a message body against your organization’s registered classification model and returns a probability for every label. It sends nothing and writes nothing to the contact: it is a read-only scoring call you make before POST /messages/send, so suppression and frequency caps see one consistent category on the send. Auth scope: messages:read. Rate limit: enforced per API key; a sustained burst returns 429 with a Retry-After header (envelope below).

Built-in vs custom classification

The built-in model ships a fixed 22-label taxonomy (the array in the 200 response below), registered per tenant: every organization scores against its own registered model instance while the label set itself stays platform-stable. Custom classification is what you compose on top of it: pass channel_hint and locale_hint to condition the scores on the send you are about to make, then map top_label onto your own category set in your code. The endpoint only returns scores; it never stores your mapping.

Request body

Field	Type	Notes
`content`	`string`	Required. The body to score, up to 4,096 characters; longer bodies return `422`.
`channel_hint`	`string`	Optional. The channel you plan to send on (`sms`, `whatsapp`, `email`). Conditions the scores on channel-typical phrasing.
`locale_hint`	`string`	Optional. BCP-47 locale of `content` (`en-US`, `de-DE`). Sharpens scores for non-English copy.

curl -X POST "https://api.orbit.devotel.io/api/v1/messages/classify" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Your Devotel verification code is 493210. It expires in 10 minutes.",
    "channel_hint": "sms",
    "locale_hint": "en-US"
  }'

// No SDK ships a typed classification helper yet — use a generic request.
const res = await fetch("https://api.orbit.devotel.io/api/v1/messages/classify", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.ORBIT_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "Your Devotel verification code is 493210. It expires in 10 minutes.",
    channel_hint: "sms",
    locale_hint: "en-US",
  }),
});
const scored = await res.json();

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("POST", "/messages/classify", json_body={
    "content": "Your Devotel verification code is 493210. It expires in 10 minutes.",
    "channel_hint": "sms",
    "locale_hint": "en-US",
})

package main

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

func main() {
	body := []byte(`{"content":"Your Devotel verification code is 493210. It expires in 10 minutes.","channel_hint":"sms","locale_hint":"en-US"}`)
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/messages/classify", 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)
}

require 'net/http'
require 'json'

uri = URI('https://api.orbit.devotel.io/api/v1/messages/classify')
req = Net::HTTP::Post.new(uri)
req['X-API-Key'] = ENV['ORBIT_API_KEY']
req['Content-Type'] = 'application/json'
req.body = {
  content: 'Your Devotel verification code is 493210. It expires in 10 minutes.',
  channel_hint: 'sms',
  locale_hint: 'en-US',
}.to_json
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/classify');
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, json_encode([
  'content' => 'Your Devotel verification code is 493210. It expires in 10 minutes.',
  'channel_hint' => 'sms',
]));
echo curl_exec($ch);

No SDK ships a typed classification helper, so the snippets above use each language’s generic request escape hatch (the SDK language policy keeps that escape hatch open exactly for endpoints like this one). The Python client.request() call is the same escape hatch the suppression samples use. 200 OK — the full 22-label score array labels always carries all 22 labels, sorted by probability descending, so your code can apply its own threshold; top_label is labels[0].label.

{
  "data": {
    "top_label": "verification",
    "labels": [
      { "label": "verification", "probability": 0.971 },
      { "label": "security_alert", "probability": 0.011 },
      { "label": "account_update", "probability": 0.006 },
      { "label": "password_reset", "probability": 0.004 },
      { "label": "transactional", "probability": 0.003 },
      { "label": "delivery", "probability": 0.001 },
      { "label": "shipping_update", "probability": 0.001 },
      { "label": "receipt", "probability": 0.0005 },
      { "label": "billing", "probability": 0.0005 },
      { "label": "payment_failure", "probability": 0.0004 },
      { "label": "order_update", "probability": 0.0004 },
      { "label": "appointment_reminder", "probability": 0.0003 },
      { "label": "reminder", "probability": 0.0003 },
      { "label": "reservation", "probability": 0.0002 },
      { "label": "alert", "probability": 0.0002 },
      { "label": "customer_support", "probability": 0.0002 },
      { "label": "conversational", "probability": 0.0002 },
      { "label": "welcome", "probability": 0.0001 },
      { "label": "marketing", "probability": 0.0001 },
      { "label": "promotional", "probability": 0.0001 },
      { "label": "abandoned_cart", "probability": 0.0001 },
      { "label": "feedback_survey", "probability": 0.0001 }
    ]
  },
  "meta": {
    "request_id": "req_cls123",
    "timestamp": "2026-08-20T11:20:00Z"
  }
}

Failed classification

Scenario	HTTP	`error.code`
`content` missing or longer than 4,096 characters	`422`	`VALIDATION_ERROR`
Request body over the payload ceiling	`413`	`PAYLOAD_TOO_LARGE`
Sustained burst past the per-key rate limit	`429`	`RATE_LIMITED`

422 — body too long

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "content must be at most 4096 characters.",
    "status": 422
  },
  "meta": { "request_id": "req_cls422", "timestamp": "2026-08-20T11:21:00Z" }
}

413 — payload too large

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body exceeds the maximum payload size.",
    "status": 413
  },
  "meta": { "request_id": "req_cls413", "timestamp": "2026-08-20T11:22:00Z" }
}

429 — slow down

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many classify requests. Honor Retry-After and retry.",
    "status": 429
  },
  "meta": { "request_id": "req_cls429", "timestamp": "2026-08-20T11:23:00Z" }
}

Worked example — classify, then suppress, then send

Classify first, gate second: score the body, stamp the winning label onto the send as its category, and let the org’s suppression and cap policies act on that category. With the suppression policy from the example above (applies_to_categories: ["marketing"]), a body that scores as verification sails through both gates; a re-run promo that scores as marketing is deduped by suppression and counted by the caps.

# 1 — score the body
curl -s -X POST "https://api.orbit.devotel.io/api/v1/messages/classify" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content":"Flash sale — 30% off all summer sandals.","channel_hint":"sms"}'
#    -> "top_label": "marketing"

# 2 — send with the scored category; suppression and caps gate on it
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" }
  }'

The same classify-first pattern composes with frequency caps: evaluate the label before you apply a cap rule, cap marketing, and leave verification and delivery uncapped. An OTP that rides a capped category by mistake is the exact failure this ordering prevents.

Errors

Scenario	HTTP	`error.code`
Bad body (missing `window_seconds`, out of bounds)	`422`	`VALIDATION_ERROR`
Caller lacks `owner` / `admin` / `developer` role	`403`	`FORBIDDEN`
Suppression not run due to opt-out rejection	`400`	`OPTED_OUT`

API Reference

All Endpoints

Message Suppression API: dedupe sends by content hash

Message Suppression API

Get the policy

Create or update the policy

Delete the policy

Policy shape

Example — dedupe marketing sends within 7 days

Recipes — cookbook-style

Recipe 1: same body to the same recipient, twice inside the window

Recipe 2: any channel blocked by opt-in (still respected)

Recipe 3: bulk on-call import + poll-and-verify

Classify a message

Built-in vs custom classification

Request body

Failed classification

Worked example — classify, then suppress, then send

Errors

See also

​Message Suppression API

​Get the policy

​Create or update the policy

​Delete the policy

​Policy shape

​Example — dedupe marketing sends within 7 days

​Recipes — cookbook-style

​Recipe 1: same body to the same recipient, twice inside the window

​Recipe 2: any channel blocked by opt-in (still respected)

​Recipe 3: bulk on-call import + poll-and-verify

​Classify a message

​Built-in vs custom classification

​Request body

​Failed classification

​Worked example — classify, then suppress, then send

​Errors

​See also

Message Suppression API

Get the policy

Create or update the policy

Delete the policy

Policy shape

Example — dedupe marketing sends within 7 days

Recipes — cookbook-style

Recipe 1: same body to the same recipient, twice inside the window

Recipe 2: any channel blocked by opt-in (still respected)

Recipe 3: bulk on-call import + poll-and-verify

Classify a message

Built-in vs custom classification

Request body

Failed classification

Worked example — classify, then suppress, then send

Errors

See also