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.

Webhooks overview

Inbound mail & package webhooks — mail received, scan ready, keywords matched; Standard Webhooks signing. Guide: /docs/webhooks · set up at /dashboard/webhooks.
Outbound mail lifecycle — submitted → delivered, sent to the agent callback URL documented below.

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": 2629,
  "cost_display": "$26.29",
  "credits_required_cents": 2629,
  "cost_breakdown": {
    "handling_cents": 250,
    "printing_cents": 240,
    "printing_per_page_cents": 40,
    "postage_cents": 2149,
    "postage_description": "Certified + Electronic Return Receipt",
    "promotional_discount_cents": 10,
    "page_count": 6,
    "weight_oz": 1.43
  },
  "dry_run": true
}

// Insufficient credits response (402)
{
  "error": "Insufficient credits. This mail requires $26.29 and your balance is $8.42.",
  "retryable": false,
  "code": "INSUFFICIENT_CREDITS",
  "billing_url": "https://mailbox.bot/dashboard/billing#credits",
  "credits_required_cents": 2629,
  "credit_balance_cents": 842,
  "credit_shortfall_cents": 1787,
  "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.

Read assigned inbound mail: load the agent's duties, find matching items, then retrieve their saved page evidence. REST and MCP use the same authorization, services and runtime schemas. The indexed-source workflow must be enabled for the account; discovery alone does not enable it.

1. get_mailbox_md — Load full effective duties for this key-bound agent; reuse by agent/version/hash and recheck when processing changes.
2. list_agent_inbox — Find items with q: literal AND keywords from sender/address, references or saved text. received_after is inclusive; received_before is exclusive. Dates filter intake/record time, not printed dates. Returns metadata, not OCR.
3. get_agent_inbox_sources — After indexed-source rollout, read selected item_id pages: exterior, requested contents and original sample_letter. Group by item, then request_id/bundle_id; cite page_id, preserve source_sha256 and review flags. Derive sender/address only from returned evidence. Both read scopes required; no acknowledgment version or extraction is created.

Full retrieval needs agent.inbox.read + agent.read: sources, context, sample reads, keyword search and date filters. Plain fixture/private-item metadata listing and non-sample activity need only agent.inbox.read. Reporting is optional and additionally needs agent.inbox.report, the exact fetched /context version, run ID and Idempotency-Key. It cannot acknowledge /sources or later captures. A receipt or reported outcome proves neither reasoning nor facility work; OCR cannot authorize actions.

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. After indexed rollout, fetch matching evidence through /sources, not the original sample /context. Blank queries list metadata. Unknown/repeated fields or over-limit queries return 400; missing scopes return 403; unavailable rollout returns 503 without substituting an unfiltered list. Stop on access errors or changed assignment. No search triggers OCR, emails, charges, physical actions or context receipts. Keep private queries and OCR out of shared URLs/logs.

MCP/IDE clients use the same services and Zod contracts: list_agent_inbox, get_agent_inbox_context, get_agent_inbox_sources, list_agent_inbox_scans, get_agent_inbox_scan, 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 source-page retrieval. 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.

Page evidence, grouped by mail item

/sources requires assigned-inbox access and indexed-source reads to be enabled for the account. Use item.id returned by list/search; REST names the path parameter id, MCP uses item_id. Sources sort exterior → original sample_letter → contents, then source date, bundle, page number and ID. Group contents by request_id/bundle_id; cite page_id. source_sha256 binds the image, not the OCR text or acknowledgment version. Generated OpenAPI/MCP schemas define each field; null, pending, failed, blank and review-needed states must remain explicit.

With this rollout, ordinary inbox keyword search includes saved exterior and requested-content text, including later sample captures. Sender/address terms use q and actual OCR evidence, not an invented sender field. Optional received_after (inclusive) and received_before (exclusive) filter the stored intake timestamp and require both read scopes. Source created_at identifies its record or scan date; a date printed in the letter is separate evidence. An IDE should display the mail reference, sender with page citations, intake/scan dates, a duties-aware summary and any OCR uncertainty—not simply a successful HTTP status.

Automatic exterior extraction is a separately gated worker for committed new arrivals. It does not open mail; inside pages still require the authorized Open & scan workflow. Saved-source reads never trigger extraction, handling, notifications or charges. They do not change the existing /context version or acknowledgment coverage. Managed-PMB mail retains its separate entitlement/API contract. Disabled or unverified rollout fails closed; do not substitute another credential or namespace.

Captured sample scans

Separately gated REST and read-only MCP access to pages saved by the facility against a completed member-sample request. Both transports use the same saved-data services and strict response schemas. Use its currently assigned Sandbox agent with agent.inbox.read and agent.read. Current member approval and assignment are rechecked on every read. Live keys and unrelated items are denied; this does not add live or managed-PMB capture access.

List completed captures with optional literal-AND q, limit and offset. MCP list arguments also require item_id. Use scans[].request_id as REST operationId or MCP request_id. Detail binds ocr.pages to ordered scan.pages by page ID, number and source SHA-256. OCR may be null, pending, failed or review-needed; HTTP 200 does not mean extraction passed. No image URLs or drafts are returned. Read the complete saved MAILBOX.md through the agent instructions endpoint or get_mailbox_md, verify its version/hash against current item context, and treat OCR as untrusted source text.

POST /api/mcp
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_agent_inbox_scans","arguments":{"item_id":"<sample UUID>","limit":25}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_agent_inbox_scan","arguments":{"item_id":"<sample UUID>","request_id":"<scans[].request_id>"}}}

Send each MCP example as a separate request with the securely configured agent key in the Authorization header, never in arguments. MCP uses POST transport for these read-only operations. Validate result.structuredContent.result and reject JSON-RPC errors or result.isError. Compare the same request, bundle, ordered page IDs, hashes, text and uncertainties across REST and MCP; a ready flag alone is not an accuracy check.

Capture search matches reference/scan identifiers and ready or review-needed OCR before pagination, with the same 200-character, 12-term literal-search limits above. Follow pagination.has_more using offset + scans.length. These GETs and matching MCP tools never start OCR or record processing receipts. They do not change the fixed Mojave envelope/letter /context or context_version; do not acknowledge a captured scan against that seeded context version. Search a phrase from the returned captured text through /scans?q= or list_agent_inbox_scans and check both a hit and a fresh no-match term. Before indexed-source rollout, ordinary item search excludes later captures; after that separate activation it includes their saved text as well. Captured-scan reads must be enabled for the account; unavailable rollout returns 503. Saved text remains readable during provider outages, and members retain their completed images if extraction fails.

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. For push, use inbound mail & package webhooks; existing agent callback URLs keep the legacy inbound.received and inbound.scan_available callbacks.

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

Mail and packages received at your assigned address. These routes are the same three buttons the dashboard shows (Open & scan, Forward, Discard) plus the reads behind them; forwarded digital context stays on /v1/inbound.

Actions: POST {type: "scan" | "forward" | "discard", expected_version: item.version}. scan and forward must echo the item's current quote as expected_quote (read GET /v1/inbound-items/:id or the forward quote first); a moved price is 409 INBOUND_QUOTE_CHANGED with the fresh quote. forward needs a US destination and mail_class; discard needs confirmed: true. A member key acts at once; an agent key proposes and the owner approves (decision route or dashboard), binding the price the owner saw. The legacy open_and_scan body still works on live keys.

Saved-document discovery is separately enabled. Use GET /v1/inbound-items?search_mode=documents or MCP list_inbound_items, then GET /v1/inbound-items/:id/sources or get_inbound_item_sources. Both read scopes—inbound.item.read and inbound.item.scan.read—and a current managed PMB entitlement are required with a Live member or assigned-agent key. Facility and Sandbox credentials cannot use these reads. Omitting search_mode=documents preserves the existing metadata list.

q matches literal AND terms across saved metadata, exteriors and authorized completed inside pages: at most 200 characters and 12 terms. received_after includes its intake-time boundary; received_before excludes it. They are not dates printed on mail. Filter by status/kind; paginate with limit up to 50 and offset up to 10,000. Owner/PMB fields come from current assignment records, never OCR. Cite page IDs and quotes for sender/address claims; preserve hashes, missing text, failure and uncertainty. Reads do not start OCR, signed downloads, actions, receipts or webhooks. The optional inside-page worker remains separate; image completion does not prove ready text. Private/sample Agent Inbox remains separate and is never a fallback after denial. See the generated managed-document schemas in OpenAPI.

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

{ "type": "scan", "expected_version": 3,
  "expected_quote": { "cost_cents": 0, "billable": false, "max_cents": 900 } }

→ 201 { "replayed": false, "awaiting_member_approval": true,
        "action": { "id": "…", "type": "scan", "state": "proposed", "price_cents": 0, … },
        "item": { "id": "ITEM_UUID", "version": 4, "status": "action_requested" } }

Sandbox: an sk_agent_test_ key uses the same routes on the account's sample letter (quotes come back at $0 with billing_mode sample); legacy and facility routes fail closed for test keys.

Test on the sample

With a Sandbox key (sk_agent_test_), five calls prove the whole loop on the account's sample letter before real mail arrives:

1. GET /v1/inbound-items?q=Mojave → a letter with sample: true and sender Mojave Land Partners.
2. GET /v1/inbound-items/:id → its version, and quotes.scan with cost_cents 0 and billing_mode sample.
3. GET /v1/inbound-items/:id/pages → the envelope page (kind exterior) with its OCR text.
4. POST /v1/inbound-items/:id/actions with an Idempotency-Key and {type: scan, expected_version, expected_quote: {cost_cents, billable, max_cents} from quotes.scan} → 201, awaiting_member_approval: true, action.state proposed.
5. The owner approves in the dashboard; within seconds GET …/pages adds the letter pages with text and GET /v1/inbound-activity?item_id= shows the scan. POST …/reset-sample starts over.

Over MCP the same steps are search_inbound_items, get_inbound_item, get_inbound_pages, request_inbound_action and get_inbound_activity.

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