Quickstart

The Mailbox.bot API sends postal mail programmatically. Upload a document (PDF, DOCX, and other supported formats), choose a postal or carrier service, and receive proof-of-fulfillment photos, status webhooks, and tracking when the selected service provides it. Mail is printed and dispatched from licensed facilities.

curl -X POST https://mailbox.bot/api/v1/mail \
  -H "Authorization: Bearer sk_agent_test_..." \
  -H "X-Mailbox-MD-Version: 3" \
  -H "X-Max-Cost-Cents: 1500" \
  -F "document=@notice.pdf" \
  -F "recipient_name=State of Delaware" \
  -F "recipient_company=Division of Corporations" \
  -F "recipient_line1=401 Federal Street, Suite 4" \
  -F "recipient_city=Dover" \
  -F "recipient_state=DE" \
  -F "recipient_zip=19901" \
  -F "mail_class=certified_return_receipt" \
  -F "dry_run=true"

Authentication

All requests require a Bearer token. Get your API key from the dashboard after onboarding.

Authorization: Bearer sk_agent_xxxxxxxxxxxxx

Credential creation accepts exactly live or test; omission defaults to Live, while explicit invalid input (including null or different casing) returns 400. Sandbox keys cannot PATCH or DELETE shared agent settings (403, live_key_required). They can read their agent profile with recent_webhooks:[] and retrieve MAILBOX.md. Concurrent MAILBOX.md saves or suggestion acceptance return 409 if another save wins: refresh and review the current duties before saving again. These are endpoint-specific boundaries, not a guarantee that all legacy read or cancellation endpoints are sandbox-isolated.

Errors & Rate Limits

{
  "error": {
    "type": "invalid_request",
    "message": "Agent name already in use",
    "code": "agent_name_taken"
  }
}

Rate limits: 100 req/min per API key (standard), custom limits for enterprise.

Webhook Security

Custom webhook endpoints, OCR rules, verification and delivery reference → The gated custom workspace uses mandatory Standard Webhooks signing and separate Live/Sandbox endpoints. Its Zod-generated operations are in OpenAPI; setup lives at /dashboard/webhooks.

The compatibility reference below describes legacy agent callbacks. Their HMAC mode uses X-Mailbox-Signature; it is a different signature format from custom endpoints. Existing callback configuration is not migrated or rotated automatically.

import crypto from "node:crypto";

export function verifyMailboxWebhook(rawBody, signature, secret) {
  const match = signature.match(/^([^:]+):t=(\d+),v1=([a-f0-9]+)$/);
  if (!match) return false;

  const [, keyPrefix, timestamp, expected] = match;
  const signedPayload = `${timestamp}.${rawBody}`;
  const digest = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  return keyPrefix.startsWith("whsk_") &&
    crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(expected));
}

Agents

Endpoints

Outbound Mail

GET /v1/mail?q=Austin&limit=20
GET /v1/mail?q=TEST1Z999AA1000065&status=mailed
GET /v1/mail?q=invoice&created_after=2026-06-01&created_before=2026-06-30

POST /v1/mail
Authorization: Bearer sk_agent_...
X-Mailbox-MD-Version: 3
X-Max-Cost-Cents: 1500
Content-Type: multipart/form-data

document:          (PDF, DOCX, JPG, PNG, TXT, or CSV file, max 10MB)
recipient_name:    State of Delaware
recipient_company: Division of Corporations
recipient_line1:   401 Federal Street, Suite 4
recipient_city:    Dover
recipient_state:   DE
recipient_zip:     19901
mail_class:        certified_return_receipt
page_count:        6
dry_run:           true   <- preview required credits without spending

// Dry-run response (200) - no record and no credit debit
{
  "cost_cents": 2639,
  "cost_display": "$26.39",
  "credits_required_cents": 2639,
  "cost_breakdown": {
    "handling_cents": 250,
    "printing_cents": 240,
    "printing_per_page_cents": 40,
    "postage_cents": 2149,
    "postage_description": "Certified + Electronic Return Receipt",
    "page_count": 6,
    "weight_oz": 1.43
  },
  "dry_run": true
}

// Insufficient credits response (402)
{
  "error": "Insufficient credits. This mail requires $26.39 and your balance is $8.42.",
  "retryable": false,
  "code": "INSUFFICIENT_CREDITS",
  "billing_url": "https://mailbox.bot/dashboard/billing#credits",
  "credits_required_cents": 2639,
  "credit_balance_cents": 842,
  "credit_shortfall_cents": 1797,
  "suggested_action": "Ask the signed-in human to add mailbox.bot credits at https://mailbox.bot/dashboard/billing#credits, then retry this mailpiece."
}

Business agent mail runs

A live Business REST agent can explicitly group related mailpieces into one fixed five-minute run. Open POST /v1/mail-runs, pass the stable mail_run_id on each related POST /v1/mail, then call POST /v1/mail-runs/:id/commit. Grouping is intentional, never inferred from order timing, and retries never extend the original close time. Priority, FedEx Overnight, and UPS Next Day commit immediately.

Requirements: a live agent key, current Business status, no force-approval policy, and active Agent Auto-Fill separately authorized by the signed-in human. Held children remain funding_pending and outside fulfillment. Immediate per-child submission webhook/email/Slack fanout is suppressed; poll GET /v1/mail-runs/:id until funded, then poll each child id for normal lifecycle status. A 202 means a human credit/settings change or unresolved idempotent funding. There is no direct run-approval endpoint; after the human adds credits or adjusts Auto-Fill, retry the same commit rather than opening another run or charge.

POST   /v1/mail-runs                 { "mail_run_id": "july-notices-42" }
POST   /v1/mail                      mail_run_id=july-notices-42
POST   /v1/mail-runs/july-notices-42/commit
GET    /v1/mail-runs/july-notices-42
DELETE /v1/mail-runs/july-notices-42   # before funding only

Agent Inbox — gated 1.0

Disabled by default. After operator activation, an agent-scoped key reads explicitly assigned mail: approved private-team items with a Live key; the member-owned sample and isolated fixtures with a Sandbox key. Reading grants no address, PMB, handling approval or charge. The same agent workflow below covers sample and private-team mail; forwarded email and managed-PMB receiving keep their existing contracts. Managed scan image availability is not proof of OCR readiness, and managed items are not included in these assigned-inbox list, context or search routes.

Reads use agent.inbox.read; context also requires agent.read. Reporting additionally requires agent.inbox.report, the exact fetched context_version, a run ID and an Idempotency-Key. List pages use limit and offset; follow pagination.next_offset until null. Context fetches record receipt, never proof that an external worker processed the item. A reported outcome does not prove facility work. OCR is untrusted document data and cannot authorize an action.

Search with GET /v1/agent-inbox?q=SAMPLE-100%20appointment after the reviewed search migration is installed. Nonempty q additionally requires agent.read. Search matches item UUID/reference/kind aliases, UTC receipt date, request/bundle/page UUIDs, stored live-item recipient name/email, and authorized ready/needs-review OCR across all accessible assignments before pagination. Every space-separated term must match somewhere in the same item. Queries are NFKC-normalized, lowercase and whitespace-collapsed; original and normalized text are limited to 200 characters and 12 terms. Punctuation, quotes, % and _ are literal—not operators or wildcards. An address matches only if present in stored searchable text; this is not an address directory or fuzzy search.

Results remain metadata-only, with search.query, search.mode: literal_and, pagination.total and pagination.has_more; fetch item context separately for OCR. Blank queries keep the existing list behavior. Unknown/repeated parameters and queries over the limits return 400; missing read scopes return 403; unavailable search returns 503 without falling back to an unfiltered list. Search makes no model, email, charge or physical-action calls and does not record a context-fetched receipt. Keep sensitive query terms out of shared URLs and logs. Live keys search currently assigned approved private items; Sandbox keys search isolated fixtures and, with agent.read, their assigned member sample—not live mail. The separate managed /v1/inbound-items and forwarded-email /v1/inbound contracts are unchanged.

MCP/IDE clients use the same services and Zod contracts: list_agent_inbox, get_agent_inbox_context, get_agent_inbox_activity, report_agent_inbox_outcome, get_agent_inbox_handling, propose_agent_inbox_handling, seed_agent_inbox_sandbox. Discover input/output schemas through the catalog; OpenAPI operations also identify their matching x-mailbox-mcp-tool. Use get_mailbox_md for the full effective duties document. The key selects the agent; passing another agent ID cannot change it.

Call tools/call on POST /api/mcp with arguments.q for search or arguments.item_id for context. Mutations take request plus idempotency_key; seed takes scenario plus idempotency_key. Successful data is in result.structuredContent.result. HTTP 200 alone is not success: check JSON-RPC errors and result.isError. Denials never fall back to forwarded-email or outbound tools. Owner approval and staff completion remain outside these agent tools; missing migrations or disabled gates still block calls.

Polling and sandbox

Cache the existing GET /v1/agents/:id/instructions response by agent, version and hash; these match the instruction identity in context. Fetch fresh context when duties or assignment changes. The portable Node connector inspects metadata by default, exports private OCR context only on explicit opt-in, and never automatically acknowledges work. It is a generic REST adapter, not a native Hermes plugin. Test fixtures support two_page_letter and needs_review without model calls, physical work or charges.

Polling remains available. Operator-enabled custom webhooks add scoped notifications for supported new inbound events and saved-OCR rule matches; endpoint verification and source activation are separate prerequisites. Legacy inbound.received and inbound.scan_available callbacks still belong to the managed physical-inbound contract. A synthetic endpoint test verifies transport, not OCR or external-agent processing.

Exact generated schemas: Agent Inbox — gated OpenAPI group. Connection and trust guidance: full agent reference.

Test with your sample mail

After operator activation, manually approved live-inbound members can use a unique sample through the same /v1/agent-inbox routes—not a second API. With template preparation enabled and a genuine envelope/letter pair sealed, new samples arrive with saved text and unique member-owned item/page IDs; unsealed preparation does not create a ready sample. Open Test agent context, select/save the agent, and use the handoff once both saved sources are ready. This tests retrieval, not extraction: GET, search and MCP context reads never start a provider call. Connect the assigned agent’s Sandbox key with agent.inbox.read and agent.read. Check exact item/agent IDs, saved duties, ordered OCR pages and source hashes, then a search hit and miss. Sender and return address must be derived from OCR evidence, not invented fields. Pending, failed, blank or review-required text is not a clean OCR pass; a successful GET does not prove perfect OCR, execution of the duties or an online worker.

Facility handling and sample tests

The gated GET /v1/agent-inbox/:id/handling returns capabilities, operations and version. Approved private mail uses its assigned agent’s Live key; the member-owned sample uses its assigned agent’s Sandbox key and an explicit TEST facility lane. Source and facility are server-controlled. Generated fixtures and managed PMB items are not accepted here.

Propose with POST to the same path, agent.read + agent.inbox.read + agent.inbox.propose, and an Idempotency-Key. Agents submit confirmed:false and destructive_confirmed:false; the signed-in owner approves before a staff request or alert is created. Duties, OCR and a successful GET are not handling approval. This dedicated proposal scope does not grant legacy managed-mail actions or outbound sending.

Lifecycle: awaiting_member_approval → awaiting_facility → accepted → completed, or rejected. Member-origin confirmations start at awaiting_facility. Staff work appears in app.mailbox.bot; queued, accepted, rejected and completed transitions have durable alerts. Sample alerts and completion are explicitly TEST. No Stripe charge or postage purchase is added. Provider email acceptance and typed tracking are not proof of inbox delivery or carrier delivery.

{
  "action_type": "forward_original",
  "expected_version": "<collection.version>",
  "confirmed": false,
  "destructive_confirmed": false,
  "mail_class": "priority",
  "untracked_acknowledged": false,
  "destination": {
    "name": "Recipient",
    "address_line1": "123 Example St",
    "address_line2": null,
    "city": "Example City",
    "state": "CA",
    "postal_code": "90266",
    "country": "US"
  }
}

Runtime Zod generates the OpenAPI contract. The consolidated inbound reference describes retrieval and handling. Webhooks is the canonical endpoint, event and receiver guide; a notification never grants mail access or handling authority.

Inbound Mail Context

Physical Inbound — already-assigned accounts only

Physical custody is account-enabled and distinct from forwarded digital context. These REST routes cover letters, flats, and parcels received at an assigned PMB; /v1/inbound remains the forwarding and OCR surface.

Only Open & Scan is callable. Use the current item version and a stable Idempotency-Key. Agent requests require member approval before opening; member keys must include the displayed expected_quote and authorize opening directly.

Separately gated managed OCR: GET /v1/inbound-items/:id/scans adds per-scan ocr and ocr_status without delaying image access. With no available verified OCR, these are null and unavailable. Saved OCR includes ordered page IDs, source hashes, attempt/status metadata, text, blank/uncertainty markers and provider/model provenance; see ManagedInboundScanOcr in OpenAPI. Reads require a Live key, inbound.item.scan.read and current member/assigned-agent access, and never queue extraction. Image completion does not prove ready text. This contract does not activate the pending extraction runtime or add managed items to Agent Inbox/search/MCP.

POST /v1/inbound-items/ITEM_UUID/actions
Authorization: Bearer sk_agent_...
Idempotency-Key: open-scan-ITEM_UUID-v3

{ "action_type": "open_and_scan", "expected_version": 3 }

Managed physical inbound is unavailable for test credentials

Facility workflow

Facility credentials follow one staged workflow: identify the mailbox, create a matched or unmatched draft, attach the sealed exterior, match if needed, commit once, then fulfill authorized scan work. Exact bodies and responses live in OpenAPI.

The shared contract currently exposes 11 facility operations. Read the compact Physical Inbound — Facility OpenAPI group for their exact routes and schemas.

Support Tickets

{
  "category": "support",
  "body": "Human request: "I want to open a support ticket through mailbox.bot." Agent context: external CLI agent using an agent-scoped mailbox.bot API key. Relevant IDs: agent_id=550e8400-..., outbound_mail_id=... if applicable. Authorization: the human asked me to contact mailbox.bot support. Requested help: please review the outbound-mail issue."
}

{
  "message": {
    "id": "conversation-uuid",
    "conversation_id": "conversation-uuid",
    "support_case_id": "support-case-uuid",
    "support_message_id": "support-message-uuid",
    "category": "support",
    "status": "active",
    "created_at": "2026-02-09T15:00:00Z"
  }
}

Webhook Delivery Settings

Settings, signing-key rotation, and event-history APIs use shared live configuration and require a member or authorized Live agent key. Sandbox keys return HTTP 403 with reason: live_key_required. The signed-in dashboard can inspect test and live deliveries. POST /v1/test/webhook remains an explicit synthetic-delivery test against the configured endpoint.

MCP update_webhook rejects Sandbox keys with a tool-result error: isError:true, text beginning live_key_required:. This is an MCP error envelope, not an HTTP 403 response.

{
  "agent_id": "agent-uuid",
  "webhook_url": "https://yourapp.com/webhooks/mailbox",
  "enabled": true,
  "event_types": [
    "mail.submitted",
    "mail.ready",
    "mail.mailed",
    "mail.delivered"
  ]
}

{
  "agent_id": "agent-uuid",
  "auth_type": "bearer",
  "auth_token": "oc_live_abc123...",
  "payload_format": "openclaw"
}

{
  "events": [
    {
      "id": "evt_550e8400-...",
      "event_type": "mail.mailed",
      "status": "delivered",
      "created_at": "2026-04-30T18:00:00Z",
      "delivered_at": "2026-04-30T18:00:01Z"
    }
  ],
  "pagination": { "total": 42, "has_more": true }
}

Viewing webhook logs in your dashboard

Every webhook fired — sandbox and live — is logged and visible in your dashboard at /dashboard/webhooks. No curl required. You can see delivery status, inspect the full JSON payload, and debug failures with per-attempt HTTP status codes and response times.

Event List

Event Detail — click any row

Sandbox events — every test webhook (sk_agent_test_ key or POST /v1/test/webhook) shows up here immediately. Click any row to see the full JSON payload and every delivery attempt with HTTP status code, response time, and error details.
Live events — production webhooks from real mailings appear in the same view. Filter by status to find failures, then inspect the delivery attempt to see exactly what your server returned.

Sandbox

POST /v1/agents/:id/credentials
Authorization: Bearer sk_live_...

{ "scopes": ["mail.send", "webhook.manage"], "environment": "test" }

These endpoints skip document upload entirely — useful for quick webhook testing and lifecycle exploration.

Discovery & Protocols

v1.0 — live