> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Inbound Country Gate — Block or Flag Inbound Origins by Country > Constrain which inbound message origins reach your inbox by originating country. Pick block, flag, or off; set an allowlist or blocklist; and understand the phone-only resolution model and fail-open behavior. # Inbound Country Gate The inbound country gate is a per-tenant policy for the inbound webhook path. It answers one question on every inbound SMS, voice, and WhatsApp-over-phone message: **which country did this originate from, and do you want it to land in your inbox?** You use it to shut down artificially-inflated-traffic (AIT) and smishing sources, or to enforce a strict data-flow posture such as EU-only inbound origins. This page is the concept guide. For the request/response schema, see [API Reference → Settings Compliance](/api-reference/endpoints/compliance). Nothing on this page makes Orbit a compliance regulator for your traffic — this is a **tenant-owned control**: you own the policy, you set it, and Orbit enforces exactly what you set. *** ## What the gate answers Inbound fraud rarely announces itself at the platform layer. A tenant in a fraud-targeted vertical (OTPs, wallets, fan-out APIs) can see a surge of inbound SMS from one or two countries pumping billable traffic, or a smishing ring injecting phishing messages into your inbox. The inbound gate lets you **drop those origins before the message lands**, or **record them for review** without dropping. What it is **not**: a compliance-gating decision, an OFAC/embargo rail, or a platform mandate. Orbit does not decide which countries you accept inbound traffic from. The gate is a tenant-owned fraud and data-flow control, not a jurisdiction filter. *** ## The three modes | Mode | Semantics | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `off` | Gate inert — every inbound origin lands normally, even if lists are configured. | | `block` | Drop the disallowed inbound message before it lands in your inbox. The webhook still responds 200 to the provider so no retry-burst occurs; the drop is silent and deliberate. | | `flag` | Accept the message, but stamp `metadata.country_flag` with the resolved ISO-2 country and the reason it tripped (`not_on_allowlist` or `on_blocklist`). The inbox surfaces flagged messages for review; nothing is dropped. | Use `flag` first when you are not sure which origins are legitimate — it tells you what the policy would have blocked without breaking any real traffic. Move to `block` once the flag view confirms the pattern. *** ## Resolution model The gate resolves the sender's origin through the same phone-country resolver the outbound allowlist uses — **libphonenumber-js with a longest-prefix fallback**. Resolution is **phone-channel only**: * An email address resolves to no country (allowed through). * A synthetic chat identifier (`bsuid:`, PSID, `line:`, `fb:`, `ig:`) resolves to no country. * The literal `"unknown"` sender resolves to no country. Non-phone senders are deliberately skipped so the gate **never mis-rejects a chat-only sender**. When the resolver cannot confidently resolve a country at all, the gate **fails open** — the message passes through. The gate only ever acts on a confidently-resolved origin, in either direction: an allowlist violation needs a resolved country that is not on the list; a blocklist violation needs a resolved country that is on it. *** ## Policy shape Three fields under `settings.fraud` configure the gate: | Field | Meaning | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `inbound_country_mode` | `block` \| `flag` \| `off`. | | `inbound_allowed_countries` | ISO-3166-1 alpha-2 allowlist. When non-empty, only these origins are accepted; a resolvable origin not on the list is a violation. | | `inbound_blocked_countries` | ISO-3166-1 alpha-2 blocklist. Consulted only when no allowlist is set; a resolvable origin on the list is a violation. | Codes are upper-cased and deduped before they are persisted, so the shape the API returns is always the shape the evaluator sees. An allowlist, when present, **wins** over the blocklist — an allowlist is the stricter, fully-specified policy, so the blocklist is ignored while the allowlist is active. Both lists empty (or mode `off`) means the gate is inert. If you set only lists and no explicit mode, the default posture is `block` — parity with the outbound allowlist's default-deny. *** ## Configuration Reads are open to any member who can read settings (S\_READ); writes are restricted to the organization owner, because this control decides which inbound origins ever reach your inbox. ```bash theme={null} curl -X PUT \ "https://api.orbit.devotel.io/api/v1/settings/compliance/inbound-country-gate" \ -H "Authorization: Bearer $ORBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "inbound_country_mode": "block", "inbound_allowed_countries": ["US", "CA"], "inbound_blocked_countries": [] }' ``` Read back the current posture: ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/settings/compliance/inbound-country-gate" \ -H "Authorization: Bearer $ORBIT_API_KEY" ``` The PUT endpoint validates the payload with exact ISO-2 shape (two letters, letters only) and rejects with `422 VALIDATION_ERROR` on anything else. *** ## How this composes with the outbound allowlist The outbound country allowlist is the counterpart control — it rejects outbound destinations to unlisted countries on SMS, messaging, and voice. The two are independent and deliberately composable: * **Outbound allowlist** constrains where your sends can go. * **Inbound country gate** constrains which origins can land. A tenant that wants an EU-only data-flow posture normally wants both: you don't dial out to the wrong country, and you don't accept inbound traffic from it either. A fraud-targeted tenant may want only one (outbound open, inbound blocked), or the inverse. Set what your traffic needs; neither control implies the other. *** ## When to use it — and cautions **Use it** when: * You are in a fraud-targeted vertical (OTP, wallet, API fan-out) and see recurring AIT or smishing from one or two origin countries. * You have a strict data-flow posture (EU-only, US-only) that should hold for inbound messages too, not just outbound sends. * You want flag-only visibility into inbound origin countries before you commit to blocking. **Cautions:** * **Default from `off`.** The gate does nothing until you configure it. Setting lists without a mode defaults to `block` — which can drop legitimate traffic the moment it lands. Start with `flag`, confirm the pattern, then move to `block`. * **Phone-channel only.** Email and chat-only senders are always allowed through; do not expect the gate to gate them. * **Fail-open on unresolvable origin.** If the resolver can't resolve a country, the message passes. A mis-E.164 sender that should be blocked is your responsibility to catch elsewhere in your fraud stack. *** ## Related references * [Compliance Posture Overview](/compliance/posture-overview) — where this row sits in the toggle map (fail-open posture alongside the outbound allowlist). * [Fraud Shield](/compliance/fraud-shield) — the triage surface for fraud alerts the platform raises; the inbound gate's flagged traffic can feed the same review workflow. * [Channel Rate Overrides](/compliance/channel-rate-overrides) — the outbound throughput rail; a different control, often set alongside the country rails. * [API Reference → Compliance](/api-reference/endpoints/compliance) — full request/response schemas for these endpoints.