Skip to main content
POST
Buy a sending domain
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.

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. 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.
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. 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.