Book a demo

list_domains

List an org's email domains

read collection tenant-private since 2026-10-01

Lists every email domain the org has claimed with verify_domain, pending or verified, ordered by domain. Each carries its status, the DNS TXT record to publish (record_name, record_value), its join_policy, and verified_at and verified_by once it is verified.

Contract

shape
collection
authority
read
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
safe
emits
none
MCP tool
list_domains
REST
POST https://api.containertradehq.com/v1/cap/list_domains

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose domains to list.

Paginated: next next_after · page_max 1000 · walk_max 1000 · ceiling declared

Response

  • items · object[]
  • next_after · stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "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 claiming it.",
            "x-data-class": "operational"
          },
          "domain": {
            "type": "string",
            "description": "The domain, lower case.",
            "x-data-class": "operational"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "verified"
            ],
            "description": "pending until the TXT record is found, then verified.",
            "x-data-class": "operational"
          },
          "record_name": {
            "type": "string",
            "description": "Where to publish the TXT record.",
            "x-data-class": "operational"
          },
          "record_value": {
            "type": "string",
            "description": "What the TXT record carries.",
            "x-data-class": "operational"
          },
          "verified_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When it was verified.",
            "x-data-class": "operational"
          },
          "verified_by": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-user-id",
            "description": "Who verified it.",
            "x-data-class": "operational"
          },
          "join_policy": {
            "type": "string",
            "enum": [
              "invite_only",
              "request"
            ],
            "description": "invite_only, or request: a person signing up at the domain is put to the org's admins as a join request.",
            "x-data-class": "operational"
          },
          "created_by": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-user-id",
            "description": "Who claimed it.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "org_id",
          "domain",
          "status",
          "record_name",
          "record_value",
          "verified_at",
          "verified_by",
          "join_policy",
          "created_by"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000
    },
    "next_after": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass as `after` for the next page; null on the last one."
    }
  },
  "required": [
    "items",
    "next_after"
  ],
  "additionalProperties": false
}

Refusals

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

Surfaces

DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates a domain
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.