> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Buy a sending domain

> Price and buy a sending domain and its addresses before sending email.

Sending needs a domain owned by the paying agent. The purchase is the only way
to set up a domain or add an address; an email never does. An owner or API
caller buys it; a goal or model cannot. To connect a name you own, use
[domain setup](https://docs.oneshotagent.com/api-reference/email/domain-setup.md).

## Price a name

`POST /v1/domains/quote` with `{ "domain": "example.com", "mailbox_mode": "relay", "addresses": ["sales"] }`.
Nothing is bought.

* `mailbox_mode`: `relay` (default) addresses send and receive with no hosted
  inbox, free. `mailbox` addresses are hosted inboxes, warmed before they send,
  with a fee per address. Fixed once bought.
* `addresses`: 1 to 10 local parts, default `["agent"]`. The first is the main
  address rotation and goals send from. The domain has only these: mail to
  another is dropped, and a send from one is refused.

A taken or premium name answers `purchasable: false` with no `quote_id`. A
purchasable one returns `quote_id`, `total_cost`, `registration_fee`,
`mailbox_provisioning_fee` (per-address fee times the count, `0` on relay),
`expires_at` and `billing`. One payment, no renewal charge; an unused domain may
be released after a warning. See [Pricing](https://docs.oneshotagent.com/pricing.md).

To add addresses to a verified domain you have, quote it with the new
`addresses`. The answer has `setup: "domain_addresses"` and prices only the new
ones, in the domain's own mode. Refusals: `409 domain_not_verified`,
`409 mailbox_mode_conflict`, `409 addresses_already_set_up`.

## Buy the exact quote

`POST /v1/domains/buy` with `X-Quote-ID`. The mode and addresses are the
quote's. Expired, used and non-setup quotes are refused. The purchase returns
`request_id` and `receipt_id` and sends no email. A failed registration, or an
address that cannot be created, is refunded as credit.

```typescript theme={null}
const quote = await agent.quoteDomain("example.com", { mailbox_mode: "mailbox", addresses: ["sales", "support"] });
if (quote.purchasable && quote.quote_id && ownerApproved) {
  await agent.buyDomain(quote.domain, quote.quote_id, { maxCost: quote.total_cost, wait: false });
}
await agent.quoteDomain("example.com", { addresses: ["billing"] }); // add an address later
```

```python theme={null}
quote = client.quote_domain("example.com", mailbox_mode="relay", addresses=["sales"])
if quote["purchasable"] and owner_approved:
    client.buy_domain(quote["domain"], quote["quote_id"], max_cost=quote["total_cost"], wait=False)
```

`email` with a domain or address that is not set up returns
`confirmation_required` with the setup quote under `setup`. `confirmNewDomain`
(Python `confirm_new_domain`) buys that exact quote and returns `setup_pending`.
MCP shows the quote; it cannot buy.

## Requirements and holds

Goal quote `context.requirements` reports account needs as `ready`, `setup` or
`owner`; the sending-domain need lists `choices` (`domain_name`,
`mailbox_mode`, `addresses`). Setup is never deducted from a goal budget. See
[requirements](https://docs.oneshotagent.com/sdk/scope-drivers.md#account-requirements).

Unmet setup holds a goal in `awaiting_setup` until the domain is ready. After
seven days it cancels with `setup_timeout` and refunds unused goal funds. See
[holds](https://docs.oneshotagent.com/api-reference/compute/status.md#setup-holds).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.