REST API

Every /v0 route with who may call it and the permission it needs, plus pagination, idempotency, composing rules, downloads and limits.

The REST API lives under /v0 on the service’s loopback URL, or on the remote access hostname for agent routes. It is the contract every other surface uses, and its paths, snake_case fields, error codes, idempotency and pagination are kept stable deliberately.

Conventions

• Authentication: Authorization: Bearer <credential>, with the owner token, an API key or an OAuth access token issued for <origin>/v0. Browser sessions use a cookie plus the X-Inbot-CSRF header on unsafe methods. When an Authorization header is present, cookies are ignored.
• Bodies: JSON with Content-Type: application/json. Unknown body fields are rejected with validation_error.
• Arrays in queries: repeat the parameter, for example ?labels=unread&labels=important.
• Time: RFC 3339 timestamps, for example 2026-10-11T08:00:00Z.
• Deletes return an empty 200. Deleting is permanent; there is no trash timer.
• Errors: { name, code, message, fix?, docs? }. See Errors and exit codes.
• Scope: for an agent, anything outside its inbox scope returns 404 not_found, checked before permissions.

In the tables, Owner means owner only, and a permission name means agents need that permission; the owner may always call it.

Pagination

List endpoints accept limit (1 to 100, default 20), page_token and, on most lists, ascending (default false, newest first). Responses contain count, limit, the items, and next_page_token when there are more.

Page tokens are opaque and bound to the query’s filters and the caller’s scope. Reusing one with different filters, or after a search index change, returns 409 page_token_stale: start again without a token. Allow and block list entries sort by entry, ascending only.

Idempotency

POST routes that send mail accept an Idempotency-Key header of 1 to 256 characters from A-Z a-z 0-9 . _ ~ -: send, reply, reply-all, forward, draft send and draft approve.

• Keys are scoped to the inbox and shared across those routes and MCP’s idempotencyKey.
• The same key with the same payload returns the original { message_id, thread_id }.
• The same key with a different payload returns 409 idempotency_conflict.
• A key becomes reusable 24 hours after its send reaches a final state. Keys for approval requests and draft sends do not expire.

Creating inboxes and drafts also accepts a client_id: repeating a create with the same client_id returns the existing resource.

Inboxes

inbot-selftest is reserved on registered domains for verification.

Threads

Each route exists inbox-scoped (/inboxes/{inbox_id}/threads/...) and instance-wide (/threads/...). Instance-wide routes resolve the thread within the caller’s scope.

Messages

All message routes are inbox-scoped: /inboxes/{inbox_id}/messages/....

Composing

The whole message, including attachments and encoding overhead, must stay under 5 MiB (413 payload_too_large). Before queueing, every recipient must pass the send and reply lists (403 message_rejected), the inbox must be active (403 inbox_paused), and a transport must be configured (503 service_unavailable).

The caller’s send policy applies to every sending route: approval returns 403 approval_required with the new draft’s ID, and read_only returns 403 missing_permission.

Drafts

Inbox-scoped routes are /inboxes/{inbox_id}/drafts/...; listing and reading also work instance-wide under /drafts.

System state labels are received, queued, sent, send_unknown, failed, delivered, bounced, complained, rejected and deferred. Message, thread and batch label edits that touch any of them return validation_error atomically; unread and custom labels remain editable.

Downloads

Attachment routes return attachment fields (attachment_id, size and optional filename, content type, disposition and content ID) alongside download_url and expires_at; the shared AttachmentResponse also declares optional text_url, which current handlers do not populate. Raw message routes return { download_url, expires_at }.

The HMAC-signed URL is a five-minute capability: fetch it (GET /v0/downloads/{token}) without a bearer header or cookie. Never share, log or publish it. It is bound to the issuing principal and listener origin; local and tunnel URLs cannot cross listeners, and a service restart invalidates them.

Downloads recheck the issuer’s activity, current permissions, inbox scope and hidden labels. Revocation or expiry of the issuing API key, OAuth access token or owner session invalidates its URL. OAuth capabilities retain their issuing audience, including /mcp. If a bearer is supplied, it must authenticate the issuing principal. An inactive issuer returns 401; a missing read permission returns 403; invalid, expired, wrong-origin, hidden or out-of-scope resources return 404. Files are returned as attachments with nosniff and no-store.

Allow and block lists

{direction} is receive, send or reply; {type} is allow or block; {entry} is the URL-encoded address or domain.

The same four routes exist under /inboxes/{inbox_id}/lists/... for inbox lists. Global lists additionally require a key without an inbox restriction.

Webhooks

Instance-wide routes are /webhooks/...; inbox routes are /inboxes/{inbox_id}/webhooks/....

Agents see only webhooks their own key created. See Webhooks and events.

Events

GET /v0/ws upgrades to a WebSocket. See Events. There is no REST route for reading the event log.

API keys

Owner only.

GET, POST, PATCH and DELETE also exist under /inboxes/{inbox_id}/api-keys, where the route fixes inbox_id.

Domains

Owner only. See Domains.

Owner

Quarantine items have quarantine_id, source_kind (buffer_object or queue_message), reason_code, first_seen, size, inbox_id and attempts (nullable when unknown), last_attempt_at, and status: quarantined, release_pending or delete_pending. Listing never decrypts mail. Quarantine routes need the local owner bearer or an owner browser session with CSRF on POST and DELETE. Agent keys and OAuth tokens receive 403, and the tunnel blocks them. Queue items hold metadata only, so retrying one returns not_supported. An unknown ID returns not_found; missing or mismatched buffer configuration, or retrying an item whose deletion is pending, returns action_required; storage or provider failures return service_unavailable. Retry released means processing and cleanup finished; the receive lists still apply and the mail may have been rejected.

Session setup, login and redeem return { csrf_token, expires_at } and set the session cookie. Browser requests must come from the service’s own origin.

Outside /v0

There is no health, version or OpenAPI route, and no general REST rate limit. Cross-origin browser requests to /v0 are rejected.