Skip to main content

​
Ascend a new market without a hard-fail posture

Entering a new country has two regret shapes: gating so loose that unregistered or mismatched traffic sails into a regulated market, and gating so tight that a first campaign hard-fails on records you could not complete yet. The country gate — Orbit’s per-country registration and sender-type check, fed by the country-rules reference — supports a middle path. This playbook walks you from first lookup to a blocked-only-on-real-signals posture you can reverse cleanly.
Every switch in this guide is tenant-owned: your scan mode, your country allowlist, your sender registrations. Orbit curates the regulatory reference and applies your posture to your traffic; it never gates outbound globally. Confirm your obligations per market with counsel — this is operations guidance, not legal advice.

​
What the federated country surface returns

GET /compliance/country-rules?channel=<channel> is read-only. It returns one row per country × channel with the allowed sender_types, a registration level of none, recommended, or required, and prose on sender behavior and content restrictions. Read it as a decision input, not as the gate itself: The fail-closed half is deliberately narrow. Two shapes can block and nothing else: an unregistered sender into a required market, and a resolved sender type outside the country’s permitted list. A country with no row at all is never blocked — an uncatalogued destination produces zero gate findings — and an empty sender_types list means “no recorded restriction,” not “deny.” The write endpoints that curate these rows are platform-admin only; your side of the surface is the read plus how you respond to it.

​
Decide a posture for a new market

Set the order before you send a single message. The objective is that your first two weeks produce evidence, while the gate’s two can-block shapes stay fail-closed against genuinely wrong traffic.
1

Flag on

With your org’s policy scan mode at warn (the default), the gate already runs on every send to the new market. A blocking-class finding — unregistered into a required market, sender-type mismatch — is recorded and returned on the message but does not stop dispatch. warn is your flag posture: every send is screened, nothing is hard-failed yet.
2

Block only on fail-closed signals

The gate’s two blocking shapes are fail-closed by design — no favorable assumption unlocks them. Registering the Sender ID flips the registration half to pass; choosing a sender identity from the country’s sender_types flips the sender-type half. Treat those two as the only knobs, and refuse to relax them with a loose scan mode.
3

Verify in preflight

Before launch, run POST /messages/lint against a draft body with channel and either recipient_country or a destination to number. The linter applies the same gate against the same rule rows and returns the verdict a real send would get — pass, warn, or block — with per-rule messages and suggestions, so “would we pass?” is answered without spending a single message.
4

Promote to strict when the evidence says so

After 14 days (the worked example below), if flagged violations are resolved — registration approved, sender types aligned — move the org to strict. From that point a blocking verdict rejects the send with POLICY_VIOLATION.

​
When the platform says the carrier wants registration

In strict mode, a send to a registration: required market without an approved Sender ID is rejected with 400 POLICY_VIOLATION, and the details.violations list names the rule country_registration_required with severity block, the destination country, and a suggestion that points you at registration. A sender-type mismatch names country_sender_type_not_permitted and lists the permitted sender types. Legacy sender-registration codes you may see from earlier integrations — SENDER_ID_NOT_REGISTERED — carry the same meaning on the SMS path. Thread that verdict into your sender resolver instead of treating it as a dead end:
  1. Read the suggestion, not just the code. The violation message names the country and the unmet condition.
  2. Fix the identity, then retry. Register the sender for that country (Sender-ID Registration) or swap to a sender/campaign that already carries an approved registration for it. Retrying the identical request fails identically — the verdict is deterministic against the rule row.
  3. Resolve at routing time. If you use sender resolution or sender pools, make “carries an approved registration for the destination country” a resolver input for required markets, so the correct sender is picked before the gate runs rather than remediated after a 400.
Do not respond to a blocked verdict by dropping back to off. That detaches the gate from every other destination too; the fix belongs to the sender, not the scanner.

​
Skip vs deny — decide on first lookup, not in bulk

For a new market profile, classify the country the first time you look it up, and record the decision on your side:
  • Deny in advance — the destination is out of scope for your business (sanctioned, uneconomic, or simply not a market you serve). Set it in your outbound country allowlist. The allowlist is empty by default — no destination restricted — and the moment you set it, it is fail-closed by design: any off-list phone destination is rejected with 422 COUNTRY_NOT_ALLOWED. A deny that lives in the allowlist is decided once, not re-decided per message.
  • Skip for now — the market is in scope but not launchable yet (no registration paperwork, wrong sender types, content not localized). Keep it out of your send lists and campaign audiences; the gate never sees the traffic, and nothing needs to be reversed later.
  • Gate — the market is launchable under the posture above: flag on, fail-closed on the two gate shapes, promote to strict after evidence.
The anti-pattern this prevents is bulk harvesting: pulling the whole country-rules table and keying a combined deny/skips list off a bulk pass. Rules are curated per country × channel and refresh from upstream feeds — a bulk snapshot drifts. Make the skip/deny/gate call per market, per channel, at the moment you plan that market.

​
Rollback check

Before you promote a market to strict — and any time you need to undo that promotion — verify what the gate would have said, not what it did say:
  1. Would-be verdicts. Re-run the same draft through POST /messages/lint under each posture. The verdict is posture- dependent: a block under strict is the same finding warn records without stopping the send. If rolling strict back to warn makes a send pass again, the gate — not flaky carrier behavior — was the enforcement point, and the underlying rule row still applies.
  2. Rule drift. Refresh GET /compliance/country-rules for the market and compare registration and sender_types against what you planned around. A country that was recommended when you launched can become required after an upstream re-sync; your rollback decision should price in the current row, not the launch-day one.
  3. Allowlist reversal. To reverse a deny, remove the country from your allowlist (or clear the list to return to the empty, unrestricted default). There is no residual gate state — the next send re-evaluates against the current list.
  4. Audit trail. Mode changes (warn → strict and back) and allowlist edits are written to your audit log, so a posture rollback is traceable to who changed what and when.

​
Worked example: 14 days of flag, then block

A retailer preparing SMS to a market whose country-rules row reads registration: required:
1

Day 0 — flag on

Scan mode is warn. Sends to the market return warn/block findings in the X-Policy-Violations header and on the message metadata while dispatch proceeds. The team shipping the campaign watches the country_registration_required findings, not a dashboard of failures.
2

Days 1–14 — remediate the flags

The flagged violation says the sender lacks an approved registration for that market, so the submittable work is the Sender-ID registration for that country, and the sender pool is adjusted to prefer the registering identity. New sends to the market stop producing country_registration_required findings as the registration lands.
3

Day 14 — move to block

Two consecutive days with zero gate findings for the market → PATCH /settings/compliance/policy-scan-mode to strict. From this point, if a new sender without an approved registration aims at that market, the gate rejects it with POLICY_VIOLATION instead of flagging it post-hoc.
4

Reversal

If a launch needs to be walked back: PATCH the mode to warn (the gate keeps screening and recording, stop hard-failing), rerun the rollback check above to confirm the finding faded, and fix at the sender layer before trying strict again.