Quickstart

Create an account

Call POST /signup/agentic. Supply the human owner's email and a domain intent — subdomain mode gives you a <slug>.agenticboxes.email domain. Fund some initial credit so the account can send right away.

curl -X POST https://api.boxes.im/api/v1/signup/agentic \
  -H "Content-Type: application/json" \
  -d '{
    "human_email": "owner@example.com",
    "domain_intent": { "mode": "subdomain", "slug_style": "word_pair" },
    "initial_credit_cents": 2000,
    "agent_callback_webhook": "https://agent.example.com/hooks/boxes"
  }'

The response includes an intent_id, your assigned full_domain, and a stripe_payment_intent with a client_secret.

Human approves the charge

Surface the link_spend_request / payment intent to the human owner — they approve the initial credit via Stripe Link. Nothing is provisioned until the payment succeeds.

Receive your API key

On payment success the platform provisions the account, its primary agent@<your-domain> address, and the first API key — then POSTs a signup.completed event to your agent_callback_webhook containing the api_key.

Send your first email

Call POST /messages/send with your API key. The key needs the send scope. The balance is checked before the send and debited after.

curl -X POST https://api.boxes.im/api/v1/messages/send \
  -H "Authorization: Bearer bxs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "someone@example.com",
    "subject": "Hello from my agent",
    "text": "This email was sent programmatically via agenticboxes.email."
  }'

The response carries a message_id and a billing breakdown. Pass an idempotency_key to make retries safe.

Receive inbound mail

Mail sent to any address on your domain is delivered to your callback webhook as a mail.received event. Set or update that URL anytime with PUT /account/callback-webhook (needs the admin scope).

curl -X PUT https://api.boxes.im/api/v1/account/callback-webhook \
  -H "Authorization: Bearer bxs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "agent_callback_webhook": "https://agent.example.com/hooks/boxes" }'

Top up credit

When the balance runs low, call POST /account/credit/topup (needs the admin scope). It returns a Stripe payment intent the human approves — same flow as the initial signup funding.

curl -X POST https://api.boxes.im/api/v1/account/credit/topup \
  -H "Authorization: Bearer bxs_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 5000 }'