Get Started

Quickstart

The Mailbox.bot API sends postal mail programmatically. Upload a document (PDF, DOCX, and other supported formats), specify a carrier, and receive tracking numbers, proof-of-fulfillment photos, and delivery confirmations via webhook. Mail is printed and dispatched from licensed facilities.

For AI agents: Get the full reference as a single LLM-friendly file at mailbox.bot/llms-full.txt, or browse the index at llms.txt.
Sandbox
Test every endpoint and workflow with no charges. Test keys (sk_agent_test_) work on production endpoints — real document validation, real cost previews, signed webhooks. Zero code changes when you go live.
Sandbox docs →
What you can send
Letters and documents — legal notices, invoices, tax forms, compliance filings, demand letters. Upload a PDF, DOCX, JPG, PNG, TXT, or CSV and it ships as First Class, Priority, or Certified with return receipt.
Postcards and mailers — marketing campaigns, appointment reminders, thank-you cards. Design your document, we print and mail it.
Batch mail — upload a CSV of recipients and a template document. Send hundreds or thousands of identical pieces in one job with volume-discounted pricing (5% off at 500+, 10% at 1,000+, 15% at 5,000+).
Overnight and express — FedEx Overnight, FedEx 2Day, UPS Next Day, UPS Ground. Same API, same workflow — just change the mail_class field.
What happens after you hit send
1 Submitted — your document is validated (page count, dimensions, file size), cost is calculated per page + postage + any color surcharge, and your card is charged via Stripe. Webhook: mail.submitted
2 Printed and prepared — the facility prints your document, photographs the printed pages and sealed envelope as proof of fulfillment, and marks it ready for dispatch. Webhook: mail.ready with fulfillment_photos
3 Mailed — dispatched via your chosen carrier. You receive a carrier-format tracking number, dispatch method (post office drop-off, carrier pickup), and an optional postage receipt photo. Webhook: mail.mailed with tracking_number + carrier
4 Delivered — final confirmation. Webhook: mail.delivered

Every webhook is HMAC-SHA256 signed. Your dashboard shows a visual progress tracker with all fulfillment photos, tracking info, and timestamps at each stage.

Transparent pricing
Per-page printing — charged per page (B&W or color). No flat fees, no minimums.
Actual carrier postage — calculated from page count, weight, destination ZIP, and mail class. You pay what USPS/FedEx/UPS charges.
Immediate Stripe charge — charged at submission via PaymentIntent. No surprise invoices. Every response includes cost_cents, cost_display, and a full cost_breakdown so you know exactly what was charged and why.
Dry-run cost preview — send dry_run=true with your real document to get an exact cost breakdown without creating a record or charging. Use this to confirm pricing before committing.
Sandbox cost preview — test keys return estimated_live_cost_cents + cost_breakdown with no actual charge, so you can verify pricing before going live.
Production-grade sandbox
The sandbox runs the exact same pipeline as production. Your test key (sk_agent_test_) works on the same endpoints with the same request format — the only differences are no Stripe charge and no postal mail. Everything else is real:

Document validation — your document is parsed, page-counted, and checked for dimensions just like production.
Accurate cost calculation — real per-page printing + real carrier postage rates returned as estimated_live_cost_cents with a full breakdown.
HMAC-signed webhooks — your webhook endpoint receives signed payloads at every lifecycle step so you can validate your signature verification.
Always-present test_mode field — every response includes test_mode: true or test_mode: false — never omitted. Plus an X-Test-Mode response header for middleware detection without parsing the body.
Simulated facility fulfillment — advance your test record through the lifecycle and receive fulfillment photos, carrier-format tracking numbers (USPS, FedEx, UPS), dispatch confirmations, and delivery status — exactly matching what production webhooks deliver.
Dashboard verification — test records appear in your dashboard Webhooks tab with delivery status, payload inspection, and attempt-by-attempt debugging. The Mail tab shows the full progress tracker with photos, tracking, and timestamps.
Go live — swap sk_agent_test_ for sk_agent_. Zero code changes.
Also included
Inbound mail and packages — private beta — provision a real U.S. street address, get notified when something arrives, request document scans and photo intake, forward packages to any address. Inbound access requires identity verification, Form 1583, and facility approval.
Standing instructions — set rules so your agent handles mail automatically (scan all envelopes, forward packages over 2 lbs, shred junk).
Multi-protocol support — REST, MCP (Model Context Protocol), A2A (Google Agent-to-Agent), OpenClaw. Same capabilities across all protocols.
Approval workflows — require human approval in the dashboard before mail is printed, if your use case needs a human in the loop.
member → agent → endpoint → package → event

Authentication

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

Authorization Header
Authorization: Bearer sk_agent_xxxxxxxxxxxxx
Member keys (sk_live_) — full account access, all scopes, queries span all agents
Agent keys (sk_agent_) — scoped to a single agent. This is the key type you give to your AI agent.
Test keys (sk_agent_test_) — same as agent keys but activates sandbox mode. No charges, full validation. Swap to a live key when ready.
Facility keys (sk_facility_) — scoped to a facility for external scanner apps

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▸
GET/v1/mailboxesList all endpoints▸

Outbound Mail

Submit a document (PDF, DOCX, JPG, PNG, TXT, or CSV) and a recipient address — we print, envelope, apply postage, and mail it. Photo proof at every step, carrier tracking, and webhook events pushed back in real time.
Billing: With a production key, POST /v1/mail charges the member's card on file immediately. Four safeguards:
1. Cost cap — send X-Max-Cost-Cents: 1500 header. If the computed cost exceeds it, the request is rejected (422) before any charge — no record created, no money moved.
2. Dry run — send dry_run=true to validate your document and get an exact cost breakdown without creating a record or charging.
3. Approval flow — send requires_approval=true to defer charging until the member approves in their dashboard.
4. Test keys — use an sk_agent_test_ key during development. Identical flow, zero charges. Swap to a live key when ready.
5. Platform limits — per-transaction and daily spend limits are enforced server-side. If a charge exceeds either limit, the request is rejected (422) before any charge. Contact support if you need higher limits.
POST/v1/mailSend outbound mail▸
GET/v1/mailList outbound mail▸
GET/v1/mail/:idGet outbound mail details▸
DELETE/v1/mail/:idCancel outbound mail▸

Packages — inbound private beta

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 — inbound private beta

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 — inbound private beta

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 — inbound private beta

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 — inbound private beta

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 — inbound private beta

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▸
GET/v1/webhooks/eventsList webhook delivery events▸
GET/v1/webhooks/events/:eventIdGet event detail + delivery attempts▸
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
Dashboard Webhooks tab showing webhook event list with status filters and delivery status badges
Event Detail — click any row
Webhook event detail modal showing delivery attempts with HTTP status codes, response times, and full JSON payload
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

Test the full outbound mail lifecycle without printing real mail or incurring charges. The sandbox validates your document, calculates accurate postage, fires HMAC-signed webhooks, and simulates the complete facility fulfillment workflow — including proof-of-fulfillment photos, carrier-format tracking numbers, and dispatch confirmations — so your integration handles every production scenario before a single piece of real mail is sent.
How it works
1. Create a test API key — call POST /v1/agents/:id/credentials with "environment": "test". You get an sk_agent_test_ key.
2. Use the same endpoints — sandbox keys work on every production endpoint (mail, packages, actions, agents, webhooks). Same routes, same headers, same body shape. The four /v1/test/* helpers below exist only to synthesize state you can't produce locally (a fake inbound package, a manual webhook fire, a no-PDF mail submission, a lifecycle step).
3. No charge — the response includes cost_cents: 0 (no Stripe charge) plus estimated_live_cost_cents showing exactly what production would cost, with a full cost_breakdown (printing per page, postage by class, color surcharge).
4. Webhooks fire normally — your webhook endpoint receives HMAC-signed payloads with the same structure as production.
5. Advance through fulfillment — call POST /v1/test/mail/:id/advance to step the record through submitted → ready → mailed → delivered. Each step simulates real facility work: fulfillment photos, tracking numbers, dispatch method. Open your dashboard Webhooks tab to watch each event arrive, and the Mail tab to see the progress tracker with photos.
6. Go live — swap sk_agent_test_ for sk_agent_. No code changes.
Create a test key
POST /v1/agents/:id/credentials
Authorization: Bearer sk_live_...

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

Returns an sk_agent_test_ key. Use it on any production endpoint — same code, no charge, HMAC-signed webhooks fire normally.

Test Key vs Production
sk_agent_test_sk_agent_
EndpointPOST /v1/mailPOST /v1/mail
BodyMultipart (real document)Multipart (real document)
Document validationFull validationFull validation
HeaderX-Mailbox-MD-VersionX-Mailbox-MD-Version
Chargecost_cents: 0Real Stripe charge
Cost breakdowncost_breakdown: {...}cost_breakdown: {...}
Cost estimateestimated_live_cost_centsdry_run=true for preview
test_mode fieldtrue (always present)false (always present)
X-Test-Mode headertruefalse
WebhooksHMAC-signedHMAC-signed
FacilityNot queuedReal fulfillment
Webhook logsDashboard → WebhooksDashboard → Webhooks
Go liveSwap the key—
Policy & Cost Guards

These guards apply identically to both sandbox and live keys — test the integration once and the same protections run in production:

dry_run=true — add the form field on POST /v1/mail to validate the document and return the full cost_breakdown + warnings array without creating a record or charging. Works with any key.
X-Max-Cost-Cents — set this header to a cap (e.g. 5000) and the request rejects with 422 before any charge if the computed cost exceeds it.
force_approval — set on the credential at mint time. Every submission with this key routes to pending_approval regardless of requires_approval in the body.
max_daily_pieces — set on the credential to cap outbound mail per 24h window per key. Surfaces as a warnings entry in dry_run; rejects with 422 once exceeded.
Dashboard segmentation — sandbox traffic appears under the orange Sandbox tab on /dashboard/mail and /dashboard/webhooks. Live and test data never co-mingle in the default views.
Quick Test Hooks

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

POST/v1/test/mailCreate test outbound mail▸
POST/v1/test/mail/:id/advanceAdvance test mail status▸
POST/v1/test/webhookFire a test webhook event▸
POST/v1/test/packagesCreate test inbound mailpiece▸

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