Domain purchase

AgentMail supports two onboarding paths:

1. Bring your own domain (BYOD) — register a domain you already own, add TXT/MX manually, verify, configure webhook.
2. Purchase a domain — search, pay via Stripe Checkout (production) or mock wallet (local dev), auto-provision MX/TXT/SPF at the registrar, auto-verify, configure webhook.

Both paths converge on the same lifecycle: pending_verification → verified → mx_pending → live.

Search

curl -sS -H "Authorization: Bearer $API_KEY" \
  "https://api.agentinbox.pro/api/domains/search?q=myagent&tlds=com,io"

Returns one result per candidate domain with the lowest available price across configured registrars (NameSilo, OpenProvider, or mock in dev). Each result includes the selected registrar.

Purchase

curl -sS -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"myagent.com","years":1}' \
  https://api.agentinbox.pro/api/domains/purchase

Purchase re-quotes all configured registrars and registers through the cheapest available option. Optional registrar overrides that selection when you need a specific provider.

Local dev (mock wallet)

With BILLING_PROVIDER=mock (default), each workspace starts with $50.00 mock balance. Purchase completes synchronously and returns 201.

Production (Stripe Checkout)

With BILLING_PROVIDER=stripe, purchase returns 202 with a checkout_url. Complete payment in the browser; AgentMail registers the domain after Stripe confirms payment via webhook.

Optional body fields for Checkout redirects:

{
  "domain": "myagent.com",
  "years": 1,
  "success_url": "https://your-app.example/success",
  "cancel_url": "https://your-app.example/cancel"
}

If omitted, defaults use AGENTMAIL_PUBLIC_URL/purchase/success and /purchase/cancel.

After purchase:

• Registrar registers the domain
• DNS host adapter creates MX → mx.agentinbox.pro, TXT verification, SPF (v=spf1 -all)
• workers/domain-provision polls and auto-verifies once DNS propagates
• Agent configures webhook via PATCH /api/domains/:id/delivery

Poll order status:

curl -sS -H "Authorization: Bearer $API_KEY" \
  https://api.agentinbox.pro/api/domains/orders/$ORDER_ID

BYOD (unchanged)

curl -sS -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"existing.example.com"}' \
  https://api.agentinbox.pro/api/domains

See DNS setup for manual TXT/MX steps.

SPF and DKIM

• SPF — created at purchase as v=spf1 -all (anti-spoofing). Not required for inbound delivery.
• DKIM — not created in v1. DKIM signing applies to outbound mail (out of scope). Inbound DKIM is verified on the sender’s signature.

Renewals and transfer-out

Renewals (deferred): No grace period in the planned policy. If renewal payment fails, the registrar drops the domain and AgentMail detaches it.

Transfer-out: AgentMail does not operate transfer-out workflows. Domains follow registrar expiry and transfer policies. Auth/EPP codes may be exposed via a future read-only API; v1 does not surface them.

Environment variables

Variable	Purpose
REGISTRAR_PRIMARY	Tie-breaker when registrars quote the same price: mock, namesilo, openprovider
REGISTRAR_TLD_MAP	Optional TLD routing, e.g. com:namesilo,com:openprovider
NAMESILO_API_KEY	NameSilo API key
NAMESILO_SANDBOX	1 for sandbox endpoint
OPENPROVIDER_USER_NAME	OpenProvider RCP username
OPENPROVIDER_USER_PASSWORD	OpenProvider RCP password
OPENPROVIDER_API_BASE	Optional API base (default https://api.openprovider.eu/v1beta)
OPENPROVIDER_NS_GROUP	NS group for new domains (default dns-openprovider)
OPENPROVIDER_OWNER_HANDLE	Optional existing customer handle (auto-created if unset)
OPENPROVIDER_CONTACT_*	Optional platform contact fields for auto-created customer
OPENPROVIDER_INTEGRATION	Set 1 to run live adapter integration tests
BILLING_PROVIDER	mock (local dev) or stripe (production)
DOMAIN_MARKUP_CENTS	Flat markup added to wholesale quotes (default 299 = $2.99 per domain)
STRIPE_SECRET_KEY	Stripe API secret key
STRIPE_WEBHOOK_SECRET	Stripe webhook signing secret
AGENTMAIL_PUBLIC_URL	Public control plane URL for default Checkout redirects