# Domains and onboarding

An inbox can use the Extrovert domain included with your plan, a dedicated inbox subdomain from a
domain your organization already owns, or a new domain purchased through the human-controlled
commerce flow.

Paid accounts without a custom domain use `extrovertmail.com`. When free signup is enabled, free
accounts use the separate `free.extrovertmail.com` pool. Free signup is currently disabled.

## Choose a domain path
**Included domain**
Create an inbox without DNS work. Omit `username` and `domain` to use the platform domain for
    the account's plan.

**Use a domain you own**
Choose a dedicated inbox subdomain, such as `agents.example.com`, and add the returned nameserver
    records. Extrovert manages mail setup inside that subdomain without changing the rest of your DNS.

**Purchase a domain**
An agent can quote and request a registration. A signed-in billing member or an existing purchase
    limit must authorize the exact request before payment and registration.

## Use a domain you own

In the console, enter the domain you own, such as `example.com`, then choose an inbox subdomain. The
default is `agents`, producing `agents.example.com`. Your website, existing email, and other DNS
records remain unchanged.

1. Create the complete inbox domain, such as `agents.example.com`, with `mode: "ns_delegated"`.

2. Add the returned `NS` records at your DNS provider. Extrovert uses three authoritative
   nameservers: `ns1.extrovert.dev`, `ns2.extrovert.dev`, and `ns3.extrovert.dev`.

3. Extrovert publishes the required inbound and authentication records for the delegated zone.

4. Poll the domain or run verification until its status is ready for inbox creation.

5. Create inboxes with `domain: "agents.example.com"`, subject to the key's allowed domains and project
   access.

Delegation allows Extrovert to rotate or repair mail records without asking the customer to update
individual values. Do not point a CNAME at Extrovert as a substitute for delegation.

## Domain access and visibility

| Operation | Required permission |
|---|---|
| List, inspect, verify, or offboard a customer-controlled domain | `domain:manage` |
| Connect a domain you own with nameserver delegation | `domain:manage` |
| Quote, request, inspect, or cancel an agent's purchase request | `commerce:request` |

An agent's `commerce:request` permission does not approve payment and does not grant direct registrar
access.

Customer-controlled domains may be organization-wide or project-bound:

| `scope` | Visibility |
|---|---|
| `org` | Available to eligible projects in the organization |
| `project` | Available only to the key's fixed project |

A `project_id` in the request is an assertion. It cannot move the key into another project.

## Purchase request flow

1. **Quote.** `quote_domain` returns availability, the exact registration and renewal price, quote
   expiry, and any plan requirement. A quote does not reserve, charge, or register the domain.

2. **Request.** `request_domain_purchase` records the quoted commercial facts under a stable
   idempotency key.

3. **Authorize.** If no matching purchase limit allows the request, Extrovert notifies the billing
   owner and returns a signed-in approval URL. The agent cannot approve its own request.

4. **Recover payment if needed.** If additional payment authentication is required, the console keeps
   the person on the same durable request and resumes afterward.

5. **Register and configure.** Payment confirmation queues registration, DNS, and mail setup. Only the
   `ready` state means inboxes can use the domain.

Purchase limits may constrain budget period, per-purchase amount, domain count, extensions, premium
status, and applicability. The most restrictive matching control wins. Plan capacity and purchase authority
are separate checks.
**A waiting state is not a completed purchase:** `awaiting_human_approval`, `payment_action_required`, `queued`, `purchasing`, and `provisioning` do
  not mean the domain is ready. Poll the durable request and act on its `reason_code`, next action,
  human-action URL, and recommended interval.

Extrovert supports new registrations in this flow. Domain transfers are not supported. Registration
fees are non-refundable after a successful purchase, and renewal consent remains separate from the
authority to acquire a domain.

## Offboarding

Offboarding a domain can affect every inbox on it. Resolve or remove dependent inboxes before starting
the teardown job, then poll the returned job id to a terminal state. Cross-project dependencies remain
subject to organization and project access checks.

## Next

- [Purchase approvals for agents](https://docs.extrovert.dev/concepts/purchase-approvals-for-agents/)
- [Inboxes](https://docs.extrovert.dev/concepts/inboxes/)
- [Authentication and keys](https://docs.extrovert.dev/quickstart/authentication/)
- [Deliverability and limits](https://docs.extrovert.dev/concepts/deliverability-and-limits/)