mailbox.bot API

Micro-fulfillment API for developers and AI agents. Provision receiving addresses, manage packages, and get structured webhooks via MCP, A2A, OpenClaw, or REST.

member → agent → endpoint → package → event

Authentication

All requests require a Bearer token. Get your API key from the dashboard after KYC verification via Stripe Identity.

Authorization Header
Authorization: Bearer sk_live_xxxxxxxxxxxxx

Two key types are supported: member keys (sk_live_) with full account access, and agent keys (sk_agent_live_) scoped to a specific agent's resources.

Errors & Rate Limits

200 Success
201 Resource created
400 Invalid request
401 Unauthorized
429 Rate limit exceeded
500 Server error
{
  "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

Every webhook includes an X-Mailbox-Signature header containing an HMAC-SHA256 signature. Create signing keys via the API and rotate them without downtime.

Agents

Register AI agents and manage their credentials. Each agent gets a slug, subdomain endpoint, and can own multiple logistics endpoints. Provenance: member → agent
POST/v1/agentsRegister a new agent▸
GET/v1/agentsList your agents▸
GET/v1/agents/:agent_idGet agent details with stats▸
PATCH/v1/agents/:agent_idUpdate agent settings▸
DELETE/v1/agents/:agent_idDeactivate agent▸

Endpoints

Provision physical logistics endpoints for your agents. Each endpoint gets a unique reference code at a facility. Provenance: member → agent → endpoint
POST/v1/mailboxesProvision a physical endpoint (~3 seconds)▸
GET/v1/mailboxesList all endpoints▸

Packages

Track everything about received packages — photos, OCR, label data, event timeline, bailee storage status. Full provenance chain: member → agent → endpoint → package
GET/v1/packagesList packages with filters▸
GET/v1/packages/:package_idFull package payload▸
📡 POST → your-agent.example.com/webhook
{
  "event": "package.received",
  "package_id": "pkg-uuid",
  "mailbox_id": "MB-7F3A2K9P",
  "suite": "7F3A",
  "agent": "procurement-bot",
  "carrier": "fedex",
  "tracking": "794644790132",
  "weight_oz": 12.4,
  "photos": [
    "https://cdn.mailbox.bot/pkg/7F3A2K9P_001.jpg"
  ],
  "received_at": "2026-02-09T14:32:00Z"
}

Forwarding

Request package forwarding to any address. Specify carrier, service level, insurance, and signature requirements. BILLABLE
POST/v1/packages/:package_id/forwardRequest forwarding▸
GET/v1/packages/:package_id/forwardGet forwarding status▸

Actions

Unified action system. Forward, shred, scan, hold, dispose, or return packages through a single endpoint. Actions are queued, tracked, and billed automatically. BILLABLE
POST/v1/packages/:package_id/actionsRequest an action▸
GET/v1/packages/:package_id/actionsList actions for a package▸
GET/v1/packages/:package_id/actions/:action_idGet action details▸
PATCH/v1/packages/:package_id/actions/:action_idPush agent update▸

Scanning

Document intelligence. OCR, structured data extraction, and content parsing. Get raw text and machine-readable fields from labels, envelopes, and opened documents. BILLABLE
POST/v1/packages/:package_id/scanRequest content scan▸
GET/v1/packages/:package_id/scanGet scan results▸

Agent Memory

Give your agents persistent context. Tag packages for categorization, add observation notes, and pre-register expected shipments for auto-matching on arrival.
POST/v1/packages/:package_id/tagsAdd tag▸
POST/v1/packages/:package_id/notesAdd note▸
POST/v1/agents/:agent_id/expected-shipmentsRegister expected shipment▸

Standing Instructions

Rules engine. Create standing instructions that auto-trigger actions when incoming packages match conditions. Evaluated on every package intake.
POST/v1/agents/:agent_id/rulesCreate rule▸
GET/v1/agents/:agent_id/rulesList rules▸

Webhook Auth Settings

Configure how webhooks authenticate with your endpoint. Supports HMAC signing (default), Bearer token (OpenClaw), or custom header auth. Payload can be standard JSON or OpenClaw-compatible format.
GET/v1/webhooks/settings?agent_id=:agent_idGet webhook auth settings▸
PUT/v1/webhooks/settingsUpdate webhook auth▸

Discovery & Protocols

Multi-protocol agent discovery. MCP tool catalog for Model Context Protocol, A2A Agent Card for Google's agent-to-agent protocol, OpenClaw-compatible agent card at /.well-known/agent.json, and REST API.
GET/api/mcp/toolsMCP tool catalog▸
GET/v1/agents/:agent_id/a2a/agent-cardA2A Agent Card▸
GET/.well-known/agent.jsonOpenClaw agent card▸

v1.0 — live