Book a demo

remove_domain

Remove an email domain

act entity tenant-private since 2026-10-01

Removes an email domain the org claimed with verify_domain, pending or verified. People signing up at it are no longer matched to the org. To move a domain to another org, remove it here and claim it there with verify_domain, which proves the DNS TXT record again. Repeating the same call answers the first removal, replayed. A domain the org neither has nor removed is refused unknown_domain; a domain an SSO connection or Directory Sync directory still uses is refused domain_in_use, naming which.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
natural
emits
domain.removed
MCP tool
remove_domain
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/remove_domain

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org removing the domain.
domaintextrequired3 to 253 characters
The domain, such as example.com.

Response

  • org_id · string · The org it was removed from.
  • domain · string · The domain, lower case.
  • was · string · Whether it was pending or verified when it was removed.
  • removed_by · string · Who removed it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org it was removed from.",
      "x-data-class": "operational"
    },
    "domain": {
      "type": "string",
      "description": "The domain, lower case.",
      "x-data-class": "operational"
    },
    "was": {
      "type": "string",
      "enum": [
        "pending",
        "verified"
      ],
      "description": "Whether it was pending or verified when it was removed.",
      "x-data-class": "operational"
    },
    "removed_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who removed it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "domain",
    "was",
    "removed_by"
  ],
  "additionalProperties": false
}

Refusals

  • unknown_domain · 422 · the org neither has the domain nor ever removed it
  • domain_in_use · 409 · an SSO connection or Directory Sync directory still uses the domain

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a domain removal
  • Outbound: crosses to no counterparty

Events

Related

create_sso_connection, set_domain_join_policy, verify_domain