Skip to main content
By default an agent’s mailbox lives on wireboxmail.com. Custom domains let agents send and receive from a domain you own — for example eva@agents.example.com — so customer-facing email carries your brand instead of Wirebox’s. Domains are registered per organization, verified once, and can then be shared by every identity in the organization.

​
Apex or subdomain?

You can register either an apex domain (example.com) or a subdomain (agents.example.com). A subdomain is the safer default. Inbound email for a domain is routed by its MX records, so pointing the apex at Wirebox redirects the mail for every address on that domain. A subdomain leaves your existing human mailboxes untouched and is easy to remove later. Use the apex only if the domain is not used for email yet.

​
Before you start

  • A domain you own, with access to edit its DNS records at your registrar.
  • An API key for the organization, or access to the Console.
  • A few minutes for DNS propagation.

​
Step 1: Add the domain

The response contains the domain object and its dns_records array. Each record has a type, a name (host), a value, an optional priority, a per-record status (pending, valid, or failed), and a human-readable purpose. Treat the values as opaque strings and copy them exactly. The first domain added to an organization is marked as the default automatically; you can change the default once a domain is verified.

​
Step 2: Add the DNS records

Publish every record returned for the domain. They typically cover:
If the domain already receives mail elsewhere (Google Workspace, Microsoft 365, another mailbox provider), changing its MX records redirects all inbound mail for that domain. Register a subdomain instead unless you intend to move the whole domain.
Keep the records in place after verification — removing them breaks inbound mail and DKIM signing.

​
Step 3: Verify

Recheck the domain from the Console, or call verify from the API:
cURL
Verification queries the provider and updates each record’s status plus the domain status: DNS changes take a few minutes to propagate, and re-running verify is safe.

​
Step 4: Use the domain

  • Per identity — pass custom_domain_id or domain when creating or updating an identity; its mailbox then uses that domain.
  • As the organization default — new identities that do not specify a domain use the default. Only a verified domain can be set as default:
cURL

​
Managing domains

  • List — GET /api/v1/domains returns every domain with a mailboxes_count.
  • Get — GET /api/v1/domains/{id} returns one domain with its DNS records.
  • Delete — DELETE /api/v1/domains/{id} removes the domain and its provider registration. New identities fall back to the Wirebox default domain unless another verified domain is set as default.
See the Domains API reference for response fields and error codes.

​
Troubleshooting