API

Base URL: https://api.agentinbox.pro

Authentication: workspace API key on all routes except workspace bootstrap.

Authorization: Bearer ak_live_...

Bootstrap

Create workspace

POST /api/workspaces
Content-Type: application/json

{ "name": "my-agent" }

201 — returns workspace_id, api_key (once), webhook_signing_secret.

Production bootstrap is rate-limited (3 workspaces per IP per day).

Instant inbox

Platform subdomain without BYOD DNS. Requires wildcard MX on *.inbox.agentinbox.pro in production.

Create instant inbox

POST /api/instant-inbox
Authorization: Bearer <api_key>

201 — { address, domain_id, domain, existing: false }
200 — returns existing platform inbox if workspace already has one.

Example address: inbox@abc12345.inbox.agentinbox.pro (catch-all on {slug}.inbox.agentinbox.pro).

Demo inbox (homepage)

POST /api/demo/inbox

No auth. Rate-limited by IP (same as bootstrap). Sets httpOnly cookie; returns { address, domain_id, domain }.

GET /api/demo/events

Returns { events: [...] } for the demo session cookie.

Domains

Register domain

POST /api/domains
Authorization: Bearer <api_key>
Content-Type: application/json

{ "domain": "acme-agent.com" }

201 — domain row with txt_name, txt_value, mx_target, status pending_verification.

Search domains (purchase)

GET /api/domains/search?q=myagent&tlds=com,io
Authorization: Bearer <api_key>

Returns one result per candidate domain with the lowest available price across configured registrars. Each result includes the selected registrar.

Purchase domain

POST /api/domains/purchase
Authorization: Bearer <api_key>
Content-Type: application/json

{ "domain": "myagent.com", "years": 1 }

201 (mock wallet) — order with order_id, domain_id, status, next_steps. Wallet debited before registrar call.

202 (Stripe Checkout) — order with order_id, status: pending_payment, checkout_url, next_steps. Poll order status after payment.

Re-quotes registrars and picks the cheapest available option. Optional registrar overrides that selection.

Get purchase order

GET /api/domains/orders/{orderId}
Authorization: Bearer <api_key>

Mock wallet balance

GET /api/domains/wallet
Authorization: Bearer <api_key>

Available when BILLING_PROVIDER=mock (local dev).

Stripe webhook (platform)

POST /api/webhooks/stripe
Stripe-Signature: ...

Called by Stripe after Checkout payment. Not for agent use.

Verify ownership

POST /api/domains/{id}/verify
Authorization: Bearer <api_key>

200 — status mx_pending on success.
409 — TXT not found or mismatch.

Get domain

GET /api/domains/{id}
Authorization: Bearer <api_key>

MX instructions

GET /api/domains/{id}/mx
Authorization: Bearer <api_key>

Returns MX record set pointing at mx.agentinbox.pro.

Configure delivery

PATCH /api/domains/{id}/delivery
Authorization: Bearer <api_key>
Content-Type: application/json

{ "webhookUrl": "https://your-agent.example.com/webhooks/inbound-email" }

Requires verified domain. Production webhooks must be HTTPS.

Events

Latest event

GET /api/domains/{id}/events
Authorization: Bearer <api_key>

Inspection endpoint — webhooks are the primary delivery path.

Delivery attempts

GET /api/domains/{id}/delivery-attempts
Authorization: Bearer <api_key>

Replay event

POST /api/domains/{id}/events/{eventId}/replay
Authorization: Bearer <api_key>

Domain statuses

Status	Meaning
pending_verification	Registered; TXT not yet verified
mx_pending	TXT verified; awaiting MX / first mail
verified	Ownership proven
live	At least one mail received and webhook delivered
disabled	Administratively disabled

Free tier limits

Limit	Value
Domains per workspace	1
Inbound emails per day	100
Max message size	1 MB
Retention	14 days

Error shape

{ "error": "Human-readable message" }

Common codes: 400 validation, 401 missing/invalid API key, 404 not found, 409 state conflict, 429 rate limit.

Postman

Import the production collection from the repo: docs/Agent Mail Production.postman_collection.json.

Set base_url to https://api.agentinbox.pro and agentmail_domain to a domain you control.