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. GET: returns the org’s single policy or null when none is set.

curl "https://api.orbit.devotel.io/api/v1/message-suppression/" -H "X-API-Key: dv_live_sk_your_key_here"

DELETE: turns the policy off (the operation is idempotent — a second DELETE returns the same 204).

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

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)

Using the SDKs

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

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

const res = await orbit.messageSuppression.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", "/message-suppression")

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.

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.

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

Using the SDKs

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

Errors

See also

​Message Suppression API

​Using the SDKs

​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

​Errors

​See also

Message Suppression API

Using the SDKs

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

Errors

See also