Quickstart

This guide walks through the full happy path against production: https://api.agentinbox.pro.

Replace acme-agent.com with a domain you control.

The whole flow

# 0. API base
export API="https://api.agentinbox.pro"

# 1. Create workspace — save api_key and webhook_signing_secret (shown once)
curl -s -X POST "$API/api/workspaces" \
  -H "content-type: application/json" \
  -d '{"name":"acme-invoice-agent"}'

export AGENTMAIL_API_KEY="ak_live_..."
export WEBHOOK_SECRET="whsec_..."

# 2. Register domain — save domain id + TXT challenge
curl -s -X POST "$API/api/domains" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -d '{"domain":"acme-agent.com"}'

export DOMAIN_ID="..."

# 3. Add TXT at your DNS provider, then verify
curl -s -X POST "$API/api/domains/$DOMAIN_ID/verify" \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"

# 4. Add MX at your DNS provider (see below), then set webhook
curl -s -X PATCH "$API/api/domains/$DOMAIN_ID/delivery" \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
  -d '{"webhookUrl":"https://your-agent.example.com/webhooks/inbound-email"}'

# 5. Send mail from Gmail, Outlook, or any sender
#    To: billing@acme-agent.com

# 6. Inspect latest event (webhook is the primary path)
curl -s "$API/api/domains/$DOMAIN_ID/events" \
  -H "Authorization: Bearer $AGENTMAIL_API_KEY"

That is the entire control-plane surface for a domain-bound inbox.

Step 1 — Create a workspace

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

{"name": "acme-invoice-agent"}

{
  "workspace_id": "b9ba7da2-fce3-4c9b-ac9b-4e1a8a0b2217",
  "api_key": "ak_live_...",
  "webhook_signing_secret": "whsec_..."
}

Store api_key and webhook_signing_secret securely. The API key is returned once.

All later requests use:

Authorization: Bearer ak_live_...

Step 2 — Register your domain

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

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

{
  "id": "b9ba7da2-fce3-4c9b-ac9b-4e1a8a0b2217",
  "domain": "acme-agent.com",
  "status": "pending_verification",
  "txt_name": "_agentmail-verify.acme-agent.com",
  "txt_value": "agentmail_verify_5fde4f8c1b29ef9660e67ee303b731a0",
  "mx_target": "mx.agentinbox.pro"
}

Status is pending_verification until you add DNS and call verify.

Step 3 — DNS: TXT then verify

Add this record at your DNS provider (Cloudflare, Porkbun, Route 53, etc.):

Type	Name	Value
TXT	_agentmail-verify.acme-agent.com	agentmail_verify_... (from step 2)

Then verify:

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

On success, status becomes mx_pending — ownership is proven.

Step 4 — DNS: MX record

Type	Name	Priority	Value
MX	acme-agent.com	10	mx.agentinbox.pro

After MX propagates, mail to any address on the domain routes to agentinbox.pro:

billing@acme-agent.com
invoices@acme-agent.com
alerts@acme-agent.com

No per-address registration. The domain is the inbox.

Step 5 — Configure webhook

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

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

Your endpoint must be HTTPS in production. Return any 2xx to acknowledge delivery.

Step 6 — Receive mail

Send a normal email from an external mailbox:

To:      billing@acme-agent.com
From:    vendor@example.com
Subject: Invoice #123

Attached is your invoice.

agentinbox.pro accepts SMTP → stores raw .eml → parses → POSTs JSON to your webhook.

What your webhook receives

{
  "event": "inbound.email.received",
  "event_id": "05df8afb-b4bd-4f4c-87e9-334594b9accc",
  "domain": "acme-agent.com",
  "recipient": "billing@acme-agent.com",
  "from": "vendor@example.com",
  "subject": "Invoice #123",
  "text": "Attached is your invoice.",
  "receivedAt": "2026-06-13T01:20:00.000Z"
}

Signed with HMAC headers — see Webhook events.

Domain goes live

After the first successful webhook delivery, domain status becomes live.

Minimal agent handler

// POST /webhooks/inbound-email
export async function POST(request) {
  const rawBody = await request.text();
  const event = JSON.parse(rawBody);

  // verify signature with WEBHOOK_SECRET (see webhook guide)
  await routeByRecipient(event.recipient, event);

  return Response.json({ ok: true });
}

Route on recipient — that is how you multiplex agents on one domain.

Troubleshooting

Symptom	Check
Verify returns 409	TXT not propagated yet — wait and retry
Mail not arriving	MX record points to mx.agentinbox.pro priority 10
Webhook not firing	Domain verified + webhookUrl set + HTTPS reachable
401 on API calls	Authorization: Bearer ak_live_... header present

What’s next

• DNS setup — registrar-specific notes
• Webhook events — payload fields and signature verification
• API reference — all endpoints