Skip to main content

​
Emergency Stop

The emergency stop is an org-wide kill switch — one flag, owned by your organization, that halts every outbound dispatch path (SMS, MMS, voice origination, dialer campaign activation) until you lift it. It exists for the moment when throttling a channel or scrubbing a list is not enough: a suspected breach, a runaway campaign, a litigator or carrier exposure you need frozen now. Only the owner or admin roles can read status, activate, and deactivate the switch; developer and viewer roles receive 403. The scope is your organization only — you operate the switch, Orbit operates the platform.
Activation halts outbound dispatch for the entire organization immediately. Blocked sends are rejected with 403 ORG_COMPLIANCE_EMERGENCY_STOP before provider dispatch, so no balance is debited for them. Transactional Verify/OTP sends and email are not gated — those run on separate delivery paths. Deactivate as soon as the incident is resolved.
All endpoints below are rooted at https://api.orbit.devotel.io/api/v1/compliance.

​
The endpoints

Three endpoints, all owner/admin: Check status — reads active, plus activated_at, activated_by, and reason:
Response (while the switch is ON):
Activate — flips the switch ON. The body is optional; when you send one it must be a JSON object with at most one field, reason — a non-empty string (after trimming) of at most 500 characters. A body that violates the constraint is rejected with 422 VALIDATION_ERROR:
Deactivate — lifts the halt:
Both write paths are rate-limited to 5 requests per minute — one decisive click plus a few retries, never a settings-thrash vector. Deactivation clears activated_at / activated_by / reason back to null, while the activation record stays in the audit log.

​
When to use it

Reach for the emergency stop when the cost of one more outbound send exceeds the cost of halting everything:
  • Suspected breach — a compromised API key or sender behaving outside policy.
  • Runaway campaign — a misconfigured campaign or content mistake dispatching at volume.
  • Litigator or carrier exposure — a complaint spike, carrier block notice, or regulator inquiry mid-flight.
For narrower problems use a narrower control: a bad list is a DNC scrub case, a channel-specific pause is a channel rate override, and individual contacts belong on opt-out suppression.

​
Interplay with send gates

Send gates (quiet hours, DNC, RND, RMD, DNO) are tenant-owned, per-decision controls: each one evaluates a specific regulatory signal before a send dispatches. The emergency stop layers on top of them as the blunt instrument — when it is active, every outbound dispatch is rejected with 403 ORG_COMPLIANCE_EMERGENCY_STOP before the individual gate chain matters. Use the gates for posture; use the stop for an incident. The fail-open semantics below interact with each gate differently; see the send-gates page for the per-gate fail-open / fail-closed posture table.

​
Recovery path

  1. Resolve the incident root cause — re-key credentials, halt the runaway campaign, scrub the bad list.
  2. POST /emergency-stop/deactivate lifts the halt (owner/admin).
  3. GET /emergency-stop confirms active: false; queued or blocked sends can then be re-dispatched.
The state is cached for at most 30 seconds at the API layer, so plan for enforcement (and lifting it) to take effect within half a minute of the POST. A per-send database round-trip would otherwise sit on the message hot path.

​
Audit verification and the fail-open posture

Audit-log records. Every activate and deactivate writes an entry to your organization’s audit log with the acting user id, the timestamp, and (on activate) the reason. The deactivation entry also records the previous activated_at / activated_by so a reviewer can pair the two events. Deactivation deliberately clears the live state fields to null — the audit log, not the live flag, is the durable record for post-incident review. Verify a drill or a real activation by querying GET /settings/audit-logs filtered to resource=organization:
A real activation writes an *.activate event pair-matched by the later *.deactivate entry on the same resource; run the filter as part of every drill so the review habit forms before an incident. Fail-open semantics. If the state lookup itself fails (a database hiccup), the gate treats the switch as not active — OFF — and logs a warning; a transient read failure cannot black-hole all outbound traffic. This is a deliberate fail-open choice on lookup failures only, and it applies only to the emergency stop — the narrower per-decision gates keep their own posture (fail-closed for DNC and RND, per the send-gates posture table). A lookup failure falls open; an explicitly ACTIVE switch always blocks. If the switch was active when the database flaked, re-POST activation once the database recovers and enforcement resumes.

​
Full runbook

This page is the API reference for the control. For the full incident operator’s runbook — when to reach for it, the fail-safes that bound it, and how to run it as a launch-day drill — see Emergency Stop Runbook. The summarized endpoint surface also lives inside Send Gates.