Opt-Out & Suppression Lists

A suppression list is the set of addresses you must never message again — people who replied STOP, unsubscribed, bounced, or complained. Honouring it is a legal requirement on every regulated channel, and Orbit treats it as a hard send-gate: a suppressed address is dropped before dispatch regardless of campaign, contact import, or API call. This page covers how suppression works, how to bulk-import an existing suppression list — for example when migrating from another platform — through a single CSV upload, and how to export the ledger back out for an audit. All endpoints below are rooted at https://api.orbit.devotel.io/api/v1/compliance.

How suppression happens

An address lands on the suppression list in several ways:

A contact replies with a STOP keyword on SMS/WhatsApp.
A contact opts out via the Preference Center.
You record an opt-out through the Consent API (opt_in: false).
You bulk-import a list (this page).

Each entry has a channel scope. The full scope set is: all, sms, voice, whatsapp, email, push, telegram, messenger, rcs. How the scope is chosen depends on the entry point:

Bulk CSV import infers the scope from the address type of each row: phone and WhatsApp addresses default to scope all — a STOP signal on a phone number suppresses every channel reachable on that number — while email addresses are scoped to email. A channel column overrides this per row (see Bulk CSV import).
The Consent API and the Preference Center always suppress scope all, regardless of whether the recorded identifier is a phone number or an email address. An opt-out through either of these entry points removes the contact from every channel.

However a phone number is suppressed, the voice and dialer gates honour it: a number that opts out on any channel stops receiving calls as well as messages. The mechanism differs by entry point. A bulk CSV import additionally mirrors phone rows onto the DNC list and flags the matching contacts. A STOP keyword, Preference Center, or Consent API opt-out is instead recorded with the all scope, which the voice and dialer gates read from the suppression list directly — the call is still blocked, but no separate DNC-list row or contact flag is written.

Bulk CSV import

POST /compliance/suppression-list/import accepts a multipart/form-data upload of a CSV file. It requires an admin or owner key and is rate-limited to 5 requests/minute.

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/suppression-list/import \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -F "file=@suppressions.csv" \
  -F "default_country=US" \
  -F "default_reason=migrated_from_legacy_platform" \
  -F "dry_run=false"

Form fields

Field	Type	Notes
`file`	file	Required. A single CSV, ≤ 25 MB, ≤ 100,000 rows.
`default_country`	string	ISO-3166-1 alpha-2. Used to normalise national-format phone numbers to E.164.
`default_reason`	string	Applied to every accepted row (≤ 512 chars).
`dry_run`	boolean	When `true`, parse and classify only — no database writes. Use it to preview a file before committing.

CSV format

The first row is a header. Column names are case-insensitive and position-independent, and common aliases are accepted:

Logical column	Accepted headers
Phone	`phone`, `phonenumber`, `mobile`, `msisdn`
Email	`email`, `emailaddress`, `mail`
WhatsApp ID	`wa_id`, `whatsapp`, `whatsappid`
Reason (optional)	`reason`, `note`, `notes`
Channel (optional override)	`channel`

Each row must contain at least one of phone / email / wa_id. A single row may carry several address types — each produces its own suppression entry. Example:

phone,email,reason
+14155550101,,replied STOP
,jordan@example.com,unsubscribed via email
+442071838750,sam@example.co.uk,complaint

If a channel column is present it overrides the default scope for that row and must be one of the scope values listed above.

Per-row results

The response reports outcomes per row. Accepted rows are written; others are classified, never silently dropped.

{
  "data": {
    "run_id": "supimp_4d…",
    "total_rows": 1000,
    "accepted": 950,
    "duplicates": 30,
    "intra_file_duplicates": 15,
    "invalid": 5,
    "errors": [
      { "status": "invalid", "reason": "invalid_phone", "raw_line": 42 }
    ],
    "by_channel": { "all": 800, "email": 150 },
    "file_sha256": "9b2e…"
  },
  "meta": { "request_id": "…", "timestamp": "2026-06-08T12:00:00.000Z" }
}

Counter	Meaning
`accepted`	Rows newly written to the suppression list.
`intra_file_duplicates`	Rows that repeat an earlier `(channel, address)` within this same file.
`duplicates`	Rows already suppressed from a prior import (skipped, no-op).
`invalid`	Rows that failed validation — see `errors[]`.
`by_channel`	Accepted counts grouped by channel scope.
`file_sha256`	Content hash of the upload, recorded for audit.

The two duplicate counters are reported separately and on purpose: intra_file_duplicates are repeats inside the file you just uploaded, while duplicates were already on your list from earlier. Neither is an error, and neither is silently swallowed — both are counted so your reconciliation adds up.

Validation reasons

Each errors[] entry carries a friendly reason and the source raw_line so you can fix and re-upload:

`reason`	Cause
`missing_address`	The row had no phone, email, or wa_id.
`invalid_phone`	Phone could not be normalised to E.164.
`invalid_email`	Email failed RFC-5321 shape validation.
`invalid_wa_id`	WhatsApp ID was not a valid E.164 number.
`row_too_long`	A cell exceeded 4096 characters.
`too_many_columns`	The row had more than 32 columns.

Limits

Limit	Value
Max file size	25 MB
Max rows per request	100,000
Max cell length	4,096 chars
Max columns per row	32
Max reason length	512 chars
Server-side timeout	60 s (a partial import returns `408` with the counts processed so far)

For volumes beyond 100,000 rows, split the file and import in batches — duplicate detection means re-importing overlapping ranges is safe.

When an import fails

Diagnose failures on two levels: HTTP-level rejections (nothing is written) and row-level classifications (the file is accepted but specific rows are not). HTTP-level rejections:

Status	Meaning	How to fix
`400 NO_FILE`	No `file` part in the multipart body.	Attach the CSV as multipart field `file`.
`400 MULTIPLE_FILES`	More than one file attached.	Send one CSV per request.
`400 CSV_PARSE_ERROR`	Malformed quoting — an unterminated `"` or a missing header row.	Re-export as RFC-4180 CSV (UTF-8); check that every quote has a closing pair.
`400 MULTIPART_PARSE_FAILED`	The body was not valid multipart/form-data.	Set `Content-Type: multipart/form-data` and don’t pre-encode the body.
`408 IMPORT_TIMEOUT`	The run exceeded the 60-second budget. The response names the rows already suppressed; the rest are not.	Split the remainder into smaller files and re-run — rows suppressed before the timeout are reported as `duplicates`.
`413 PAYLOAD_TOO_LARGE`	The file exceeds 25 MB.	Split into files under 25 MB each.
`413 TOO_MANY_ROWS`	The parsed file exceeds 100,000 rows.	Split into files of ≤ 100,000 rows each.
`415 UNSUPPORTED_MEDIA_TYPE`	The upload was not a CSV (exporting `.xlsx` is the common trigger).	Re-export as CSV (UTF-8).
`422 MISSING_ADDRESS_COLUMN`	The header row has no recognisable address column.	Include at least one of `phone`, `email`, `wa_id` as a header (aliases are listed under CSV format).
`422 VALIDATION_ERROR`	An optional form field failed validation.	Check `default_country` is a 2-letter ISO code and `default_reason` is ≤ 512 characters.
`429`	More than 5 import requests in one minute.	Wait for the window to close, then retry — queue bulk batches instead of hammering.

Row-level classifications (the errors[] entries that accompany a successful import) map to causes as follows:

`reason`	Cause	How to fix
`missing_address`	The row had no phone, email, or wa_id — or its `channel` override was not one of the allowed scopes.	Fill at least one address cell; restrict the `channel` column to the scope values listed above.
`invalid_phone`	The phone could not be normalised to E.164.	Fix the number, or pass `default_country` so national-format numbers parse.
`invalid_email`	The email failed RFC-5321 shape validation (or exceeded 254 chars).	Correct the address; stray whitespace and a missing `@` are the usual culprits.
`invalid_wa_id`	The WhatsApp ID was not a valid E.164 number.	Use the recipient’s MSISDN in E.164 form (leading `+` optional).
`row_too_long`	A cell exceeded 4,096 characters.	Shorten the cell — usually a pasted blob landed in the wrong column.
`too_many_columns`	The row had more than 32 columns.	Re-export with a single delimiter; unquoted commas inside a cell split it into phantom columns.

Only the first 100 errors[] entries are returned with full detail — the invalid counter always reflects the true total. The dashboard wizard (below) packages the surfaced rows as a downloadable skipped.csv so you can fix and re-import just the failures.

Import from the dashboard

The same endpoint is wrapped by a guided wizard at Settings → Compliance → Opt-out lists → Import suppression list — the same CSV contract, no terminal required.

Choose CSV file — pick a .csv under 25 MB. Use Download sample CSV in the dialog for a pre-formatted starting file.
Set defaults (optional) — a Default country (ISO alpha-2) to normalise national-format numbers, and a free-text Reason stamped onto every accepted row.
Preview — runs the import as a server-side dry run: nothing is written, and the dialog shows the accepted / already-listed / repeats-in-file / invalid breakdown before you commit.
Confirm import — performs the committing write. If any rows were invalid, download skipped.csv to fix and re-import them.

The wizard also enforces the file-type and 25 MB checks client-side, so a mistyped export fails before it ever reaches the API.

Export the suppression list

GET /compliance/suppression-list/export downloads the suppression ledger — the symmetric counterpart to the import above. Use it to prove to a regulator or auditor which addresses were suppressed at a given point, including bulk-imported numbers with no matching contact.

curl "https://api.orbit.devotel.io/api/v1/compliance/suppression-list/export?format=csv&status=active" \
  -H "Authorization: Bearer $ORBIT_API_KEY" \
  -o suppression-list.csv

Query parameters:

Parameter	Type	Notes
`format`	enum	`csv` (default) or `json`.
`channel`	enum	Restrict to one channel scope.
`status`	enum	`active` (default — the set every send gate actually enforces), `revoked`, or `all`.
`from` / `to`	string	Date range on `suppressed_at`. A bare `YYYY-MM-DD` date or an RFC-3339 datetime.
`limit`	integer	Rows to include (1–50,000, default 50,000).

Each row carries suppression_id, channel, address, the derived status (active or revoked), reason, source, contact_id (empty for bulk-imported addresses with no contact), notes, and the suppressed_at / revoked_at / created_at timestamps. Access is restricted to owner and admin keys, and every export run is written to the audit log. When the ledger exceeds 50,000 rows the CSV response carries an X-Export-Truncated: true header (the JSON equivalent sets truncated: true) — narrow by channel or export consecutive date windows to capture the tail.

Verify a suppression took effect

Trust but verify: after an import (or any opt-out event), confirm the send gate actually fences the address before you hand the list to a campaign.

Send a test message to the suppressed address. A direct API send to a suppressed recipient fails synchronously with HTTP 422 and the error code RECIPIENT_OPTED_OUT. In sandbox mode no carrier is touched and no balance is deducted; any recipient ending in 8 also resolves to the simulated blocked delivery receipt, which is the carrier-side view of the same fence.
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \ -H "X-API-Key: $ORBIT_SANDBOX_KEY" \ -H "Content-Type: application/json" \ -d '{"to": "+14155550101", "from": "+15005550101", "body": "gate check"}'
{ "error": { "code": "RECIPIENT_OPTED_OUT", "message": "Recipient has opted out of this channel" } }
A campaign send to the same address behaves differently by design: the recipient is skipped silently (status: "skipped", reason: "opted_out") so the batch keeps moving — check the campaign’s per-recipient report rather than expecting an error.
Confirm the entry is on the ledger. Export with the query above (status=active is the default) and check the address appears with the expected channel scope. The export is the source of truth every send gate reads — if the row is active there, the fence is up.

The two checks answer different questions: step 1 proves enforcement (the gate fires), step 2 proves scope (the entry exists with the channel you intended).

Removing a suppression (re-opt-in)

To bring an address back, record a fresh opt-in through the Consent API (opt_in: true). That revokes the matching suppression entry and clears the STOP-fence. Never re-message a previously suppressed contact without a documented, fresh consent event. Confirming the fence is down. Export with status=revoked and find the address: the row is still there for audit with status: revoked and a revoked_at timestamp — suppression history is never deleted, only revoked. Then send a small test message to the address as in Verify a suppression took effect: a successful submission (no RECIPIENT_OPTED_OUT) confirms the gate no longer fires on revoked history. Until both checks pass, treat the address as still fenced.

Consent Management — record and look up per-channel consent, and the revocation-parity treatment this page’s scope table is a part of: why a keyword STOP asserts scope all, and how /compliance/consent/history evidences the revocation endpoint the fence was written from.
Send Gates — quiet hours, DNC, RND, RMD, emergency stop, and the preference center.
DSAR — how delete / opt_out requests reach suppression.
API Reference → Opt-outs — opt-out and suppression endpoint schemas.

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Opt-Out & Suppression Lists

Opt-Out & Suppression Lists

How suppression happens

Bulk CSV import

Form fields

CSV format

Per-row results

Validation reasons

Limits

When an import fails

Import from the dashboard

Export the suppression list

Verify a suppression took effect

Removing a suppression (re-opt-in)

​Opt-Out & Suppression Lists

​How suppression happens

​Bulk CSV import

​Form fields

​CSV format

​Per-row results

​Validation reasons

​Limits

​When an import fails

​Import from the dashboard

​Export the suppression list

​Verify a suppression took effect

​Removing a suppression (re-opt-in)

​Related references

Opt-Out & Suppression Lists

How suppression happens

Bulk CSV import

Form fields

CSV format

Per-row results

Validation reasons

Limits

When an import fails

Import from the dashboard

Export the suppression list

Verify a suppression took effect

Removing a suppression (re-opt-in)

Related references