Quickstart

curl -X POST https://voru.org/v1/inboxes \
  -H "X-API-Key: ab_..." \
  -H "Content-Type: application/json" \
  -d '{"display_name":"support-bot"}'

curl -X POST https://voru.org/v1/inboxes/<id>/messages/send \
  -H "X-API-Key: ab_..." \
  -H "Content-Type: application/json" \
  -d '{"to":"you@example.com","subject":"Hello","text":"Hi","labels":["outreach"]}'

Full interactive reference (try it, schemas, auth): /v1/docs · openapi.json

API reference

Auth

Console login returns a JWT. Automation uses X-API-Key: ab_…. Humans register; agents must not self-signup.

POST /v1/auth/register — emails a confirmation link
POST /v1/auth/verify and /verify/resend
POST /v1/auth/login · /forgot · /reset (send X-Device-ID on login)
GET /v1/auth/devices — list signed-in devices
DELETE /v1/auth/devices/{id} — revoke a device session

Workspace

Current plan, limits, and usage.

GET /v1/me
GET /v1/overview
GET /v1/metrics
GET /v1/plans
GET /v1/mail/status

Inboxes and mail

One address per customer. Send, reply, threads, attachments, search, labels.

POST/GET/PATCH/DELETE /v1/inboxes
GET /v1/inboxes/{id}/credentials — IMAP 1993 / SMTP 465
POST .../messages/send · reply · reply-all · forward
GET .../messages · /search · /{id} · attachments
GET /v1/threads/{id}
POST/GET/PATCH/DELETE /v1/drafts POST .../send

Events

HTTPS webhooks (HMAC header X-AgentBox-Signature) or a WebSocket.

POST/GET/PATCH/DELETE /v1/webhooks POST .../test
WS /v1/ws — subscribe with an API key
Events: message.received/sent/delivered/bounced/complained/rejected, domain.verified

Pods, domains, keys

Isolate tenants with pods. Paid plans add a custom domain.

POST/GET/DELETE /v1/pods · .../inboxes
POST/GET/DELETE /v1/domains POST .../verify
GET/POST/DELETE /v1/lists/allow|block
POST/GET/DELETE /v1/api-keys POST /v1/inboxes/{id}/api-keys

Billing and tickets

Paid plans go through Stripe Checkout. Tickets email both sides.

POST /v1/billing/upgrade — returns checkout_url or switches in place
POST /v1/billing/stripe — Stripe webhook
POST/GET /v1/tickets POST .../messages

Outbound mail

Outbound mail is sent from agent.voru.org. IMAP is agent.voru.org port 1993, SMTP port 465. GET /v1/inboxes/{id}/credentials returns the mailbox password after you create an inbox.

Events

message.received, sent, delivered, bounced, complained, rejected, domain.verified. Signed with X-AgentBox-Signature.

Limits that matter

Free: 2 inboxes, allowlist, 20/day, footer on mail.
Third inbox or custom domain → Dev $12.
Humans register. There is no agent self-signup.

Outbound mail