Skip to main content
POST
Connect your sending domain
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; 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. 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.