Manage Domains

curl -X GET "https://api.wirebox.sh/api/v1/domains" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

{
  "data": [
    {
      "id": "dom_01J8ABC123XYZ",
      "domain": "agents.example.com",
      "status": "verified",
      "is_default": true,
      "provider": "telnyx",
      "provider_domain_id": "3f9c1d0e-8a2b-4f6e-9c1d-0e8a2b4f6e9c",
      "dns_records": [
        {
          "type": "MX",
          "name": "agents.example.com",
          "value": "mx.telnyx.com",
          "priority": 10,
          "status": "valid",
          "purpose": "Inbound Email Routing via mx.telnyx.com (Required)"
        }
      ],
      "verified_at": "2026-10-06T10:30:00Z",
      "created_at": "2026-10-06T10:00:00Z",
      "updated_at": "2026-10-06T10:30:00Z",
      "mailboxes_count": 2
    }
  ]
}

GET

api

domains

curl -X GET "https://api.wirebox.sh/api/v1/domains" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

{
  "data": [
    {
      "id": "dom_01J8ABC123XYZ",
      "domain": "agents.example.com",
      "status": "verified",
      "is_default": true,
      "provider": "telnyx",
      "provider_domain_id": "3f9c1d0e-8a2b-4f6e-9c1d-0e8a2b4f6e9c",
      "dns_records": [
        {
          "type": "MX",
          "name": "agents.example.com",
          "value": "mx.telnyx.com",
          "priority": 10,
          "status": "valid",
          "purpose": "Inbound Email Routing via mx.telnyx.com (Required)"
        }
      ],
      "verified_at": "2026-10-06T10:30:00Z",
      "created_at": "2026-10-06T10:00:00Z",
      "updated_at": "2026-10-06T10:30:00Z",
      "mailboxes_count": 2
    }
  ]
}

Custom domains let agent mailboxes use an address on a domain you own instead of wireboxmail.com. Domains are scoped to the organization: register once, verify, and any identity can use it. See the Custom Domains guide for the DNS workflow.

Domain Object

string

Unique domain identifier (dom_ prefix).

string

The registered domain name in lowercase ASCII.

string

pending, verified, or failed.

boolean

Whether new identities use this domain when none is specified. The first domain added to an organization becomes the default automatically.

string

Upstream provider handling mail for the domain (telnyx).

string | null

The provider’s identifier for the domain, when registered upstream.

object[]

Required DNS records. Each item has type (MX, TXT, or CNAME), name, value, an optional priority, a per-record status (pending, valid, or failed), and a purpose label.

string | null

ISO 8601 timestamp of the successful verification, if any.

string

ISO 8601 creation timestamp.

string

ISO 8601 update timestamp.

List Domains

Returns every domain registered in the organization, newest first. Each item also includes mailboxes_count — the number of mailboxes bound to that domain.

curl -X GET "https://api.wirebox.sh/api/v1/domains" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

{
  "data": [
    {
      "id": "dom_01J8ABC123XYZ",
      "domain": "agents.example.com",
      "status": "verified",
      "is_default": true,
      "provider": "telnyx",
      "provider_domain_id": "3f9c1d0e-8a2b-4f6e-9c1d-0e8a2b4f6e9c",
      "dns_records": [
        {
          "type": "MX",
          "name": "agents.example.com",
          "value": "mx.telnyx.com",
          "priority": 10,
          "status": "valid",
          "purpose": "Inbound Email Routing via mx.telnyx.com (Required)"
        }
      ],
      "verified_at": "2026-10-06T10:30:00Z",
      "created_at": "2026-10-06T10:00:00Z",
      "updated_at": "2026-10-06T10:30:00Z",
      "mailboxes_count": 2
    }
  ]
}

Create Domain

Registers the domain with the mail provider and returns the DNS records that must be published. The domain starts as pending (or verified if the provider already considers it verified). The first domain in an organization is marked as the default.

Body Parameters

string

required

The bare domain name, lowercase, without protocol or path (e.g. agents.example.com).

Returns 201 with the created Domain Object. Errors: 400 validation_error, 409 domain_exists, 502 upstream_provider_error.

curl -X POST "https://api.wirebox.sh/api/v1/domains" \
  -H "Authorization: Bearer $WIREBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "agents.example.com" }'

{
  "data": {
    "id": "dom_01J8ABC123XYZ",
    "domain": "agents.example.com",
    "status": "pending",
    "is_default": true,
    "provider": "telnyx",
    "provider_domain_id": "3f9c1d0e-8a2b-4f6e-9c1d-0e8a2b4f6e9c",
    "dns_records": [
      {
        "type": "MX",
        "name": "agents.example.com",
        "value": "mx.telnyx.com",
        "priority": 10,
        "status": "pending",
        "purpose": "Inbound Email Routing via mx.telnyx.com (Required)"
      },
      {
        "type": "TXT",
        "name": "agents.example.com",
        "value": "v=spf1 include:spf.telnyx.com ~all",
        "status": "pending",
        "purpose": "SPF Sender Policy Framework (Required)"
      },
      {
        "type": "TXT",
        "name": "agents.example.com",
        "value": "telnyx-domain-verification=...",
        "status": "pending",
        "purpose": "Domain Ownership Verification (Required)"
      }
    ],
    "verified_at": null,
    "created_at": "2026-10-06T10:00:00Z",
    "updated_at": "2026-10-06T10:00:00Z"
  }
}

Get Domain

Returns one domain with its current DNS records. Returns 404 when the domain does not exist in the organization.

curl -X GET "https://api.wirebox.sh/api/v1/domains/dom_01J8ABC123XYZ" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

Verify Domain

Asks the provider to recheck the domain’s DNS records and updates the domain and per-record statuses. A successful check sets status to verified and stores verified_at; otherwise the domain becomes failed and the response message points to the incomplete records. Re-running verify is safe. Returns the updated Domain Object plus a human-readable message. Returns 500 verification_failed if the provider could not be queried.

curl -X POST "https://api.wirebox.sh/api/v1/domains/dom_01J8ABC123XYZ/verify" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

{
  "data": {
    "id": "dom_01J8ABC123XYZ",
    "domain": "agents.example.com",
    "status": "verified",
    "is_default": true,
    "provider": "telnyx",
    "provider_domain_id": "3f9c1d0e-8a2b-4f6e-9c1d-0e8a2b4f6e9c",
    "dns_records": [
      {
        "type": "MX",
        "name": "agents.example.com",
        "value": "mx.telnyx.com",
        "priority": 10,
        "status": "valid",
        "purpose": "Inbound Email Routing via mx.telnyx.com (Required)"
      }
    ],
    "verified_at": "2026-10-06T10:30:00Z",
    "created_at": "2026-10-06T10:00:00Z",
    "updated_at": "2026-10-06T10:30:00Z"
  },
  "message": "Domain agents.example.com verified successfully."
}

Set Default Domain

Marks a verified domain as the organization default and clears the flag from any other domain. New identities use the default when neither custom_domain_id nor domain is provided. Returns 400 domain_not_verified if the domain has not been verified, and 404 when it does not exist.

curl -X POST "https://api.wirebox.sh/api/v1/domains/dom_01J8ABC123XYZ/set-default" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

Response: the updated Domain Object with "is_default": true.

Delete Domain

Removes the domain from the organization and deletes its registration with the mail provider. Returns 404 when the domain does not exist.

curl -X DELETE "https://api.wirebox.sh/api/v1/domains/dom_01J8ABC123XYZ" \
  -H "Authorization: Bearer $WIREBOX_API_KEY"

{
  "success": true,
  "message": "Domain 'agents.example.com' removed successfully."
}

Overview

Agent Identities

Mail

Domains

Phone

iMessage

Network Tunnels

Webhooks

Domain Object

List Domains

Create Domain

Body Parameters

Get Domain

Verify Domain

Set Default Domain

Delete Domain

​Domain Object

​List Domains

​Create Domain

​Body Parameters

​Get Domain

​Verify Domain

​Set Default Domain

​Delete Domain

Domain Object

List Domains

Create Domain

Body Parameters

Get Domain

Verify Domain

Set Default Domain

Delete Domain