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

# Connect your sending domain

> Publish DNS records and verify a domain you already own.

An owner or API caller can connect a domain they already own with `POST /v1/domains/setup`
and `{ "domain": "mail.acme.com", "mailbox_mode": "relay", "addresses": ["sales"] }`.
Authenticate with an access token or an `X-Agent-ID` and signed `x-agent-proof` with scope
`write`. There is no registration fee; it does not buy a domain, send email, or change your
DNS. Goal tokens cannot call it.

The claimed host sends and receives. Receiving publishes an MX record on it, so a
subdomain such as `mail.acme.com` leaves mail on `acme.com` untouched. Claiming the root
answers `warning: "receiving_replaces_existing_mail"` with `suggested_domain`: its MX
replaces where that domain's mail goes today.

`mailbox_mode` and `addresses` work as in the [purchase](https://docs.oneshotagent.com/api-reference/email/domain-purchase.md);
the first claim fixes both, and a retry cannot change them. Relay addresses are recorded at
no charge. A mailbox claim creates no inbox: once verified, buy its addresses through
`POST /v1/domains/quote` (`addresses_action_url`).

The response contains `dns_records` (`type`, `name`, `value`, `ttl`, and optional `priority`),
`status: "pending"`, `action_url`, `mailbox_mode`, `default_address` and `warmup` progress.
Publish the records with your DNS host, then call `POST /v1/domains/mail.acme.com/verify`. A
pending answer means DNS is not verified yet; repeat after propagation. A verified answer sets
`status: "verified"`.

Setup is safe to retry with the same account and domain. Another agent's claimed domain
returns `409 domain_unavailable`. The sending-domain need advertises this route in
`setup.alternatives`; after setup starts it becomes `owner` and holds the goal until the
domain is eligible. For a new name, [buy a sending domain](https://docs.oneshotagent.com/api-reference/email/domain-purchase.md).

Unverified claims expire seven days after setup starts; polling does not extend that window.
After expiration, verification returns `404 domain_unavailable`. Start setup again to claim
the name if it is still available. Verified domains do not expire under this rule.


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