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.

Connect MCP serverRun sandbox in PostmanView REST docsGet API key
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 →
Send a document by mail
Full endpoint ↓

The core workflow is one multipart request: upload the document, include the recipient address, set a cost cap, and optionally use dry_run=true first for a no-charge quote.

Have a member key? Use sk_live_ for setup, then create an agent credential with mail.send. Use the returned sk_agent_ or sk_agent_test_ key for this request.

Inbound thread fields are optional advanced context. Leave them out for normal outbound sends.

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_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"
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. If delivery proof is captured, it is included in fulfillment_photos. 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
First Class special — a 1-page USPS First Class letter is priced at $1.00. Extra pages still add normal per-page printing and any additional postage from weight.
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 context — use the mailing address you already have, then forward envelope photos, opened-mail photos, PDFs, virtual mailbox notices, and notes to your private mailbox.bot alias so the context is available beside outbound mail.
Real mailing and package address reservation reservations open — mailbox.bot-issued street address + mailbox number, package handling, scan/photo intake, and agent notifications are separate services that require identity verification and postal authorization where applicable. Approved address issuance begins August 2026.
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.

Copy/paste verification context
Header format: whsk_prefix:t=<timestamp>,v1=<hmac-hex>. Compute the digest over <timestamp>.<raw_json_body> using the raw 64-char secret. The whsk_ prefix identifies the key; do not include it in the HMAC input.
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

Register AI agents and manage their credentials. Each agent gets a slug, subdomain endpoint, and can own multiple logistics endpoints. Provenance: member → agent

Endpoints

Provision physical logistics endpoints for your agents. Each endpoint gets a unique reference code at a facility. Provenance: member → agent → endpoint

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▸

Upload a document as multipart form data. Supported local-only formats are PDF, DOCX, JPG, PNG, TXT, and CSV. The original file is stored in mailbox.bot storage and previewed in a same-origin print view. PDF is WYSIWYG; DOCX may require an explicit page_count when embedded Office page metadata is missing. Requires an agent-scoped key with mail.send scope and X-Mailbox-MD-Version header.

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_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 cost without charging
Key fields:
document — supported formats: PDF, DOCX, JPG, PNG, TXT, CSV
page_count — optional explicit page count for non-PDF uploads; when supplied for DOCX, TXT, or CSV it overrides local detection and makes pricing deterministic
mail_class — first_class (default), priority, certified, certified_return_receipt, fedex_ground, fedex_express, fedex_2day, fedex_overnight, ups_ground, ups_2day, ups_next_day
color — true for color printing (+$0.25/page surcharge)
requires_approval — true to require member dashboard approval before printing (no charge until approved)
inbound_capture_id — optional inbound mail item UUID when this outbound piece is replying to forwarded inbound context
postal_mail_thread_id — optional physical-mail thread UUID to keep inbound review and outbound send in one workflow
dry_run — true to validate and get cost breakdown without creating a record or charging
metadata — JSON object echoed in every response and webhook payload
Response always includes cost_breakdown with line-item detail: printing per page, postage by class and zone, and color surcharge. Submission responses also include document metadata; pdf_url is only populated for actual PDFs.
// Dry-run response (200) — no charge
{
  "cost_cents": 1257,
  "cost_display": "$12.57",
  "cost_breakdown": {
    "printing_cents": 180,
    "printing_per_page_cents": 30,
    "postage_cents": 1077,
    "postage_description": "Certified + Return Receipt",
    "page_count": 6,
    "weight_oz": 1.43
  },
  "dry_run": true
}
Errors: 400 (validation / missing fields / unsupported format / invalid page_count / DOCX page count unavailable; validation failures include a structured fields[] array) · 402 (card declined / no payment method / suspended) · 404 (no active mailbox) · 409 (MAILBOX.md version mismatch) · 422 (cost exceeds X-Max-Cost-Cents, per-transaction limit, or daily spend cap — no charge made)

Inbound Mail Context

Forward or email scans, PDFs, photos, notes, provider notices, and other context-aware documents to the renter's private alias to initiate OCR/extraction. REST and MCP tools then retrieve the captured context for LLMs and external agents; they do not upload files directly into OCR. The intended loop is: discover alias -> forward documents -> read draft_context -> draft with the LLM -> send outbound mail with inbound_capture_id and, when present, postal_mail_thread_id.

Packages — real mailing address beta

Account-enabled facility workflow for physical receiving addresses and packages. This is not required for the default inbound forwarding/OCR alias. When enabled, package APIs track photos, OCR, label data, event timeline, and storage status. Full provenance chain: member → agent → endpoint → package
📡 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 — real mailing address beta

Request forwarding for packages received through an approved real mailing address beta account. Not part of the default inbound forwarding/OCR alias. Specify carrier, service level, insurance, and signature requirements. BILLABLE

Actions — real mailing address beta

Facility-backed action system for real mailing address beta packages and mail items. Forward, shred, scan, hold, dispose, or return packages through a single endpoint. For default forwarded inbound mail context, use the Inbound Mail Context endpoints above. BILLABLE

Scanning — real mailing address beta

Facility-backed scan requests for packages received through a real mailing address beta account. For the newer bring-your-own-address flow, forward photos/PDFs/notices to your inbound alias and read OCR/extracted context through /v1/inbound. BILLABLE

Agent Memory — account-enabled

Give your agents persistent context. Tag packages for categorization, add observation notes, and pre-register expected shipments for auto-matching on arrival.

Standing Instructions — account-enabled

Rules engine. Create standing instructions that auto-trigger actions when incoming packages match conditions. Evaluated on every package intake.

Webhook Delivery Settings

Set the HTTPS endpoint that receives lifecycle events, choose event filters, and 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.
PUT/v1/webhooks/settingsUpdate webhook settings▸
Request — outbound lifecycle webhooks
{
  "agent_id": "agent-uuid",
  "webhook_url": "https://yourapp.com/webhooks/mailbox",
  "enabled": true,
  "event_types": [
    "mail.submitted",
    "mail.ready",
    "mail.mailed",
    "mail.delivered"
  ]
}

Use ["*"] for all events. Setting webhook_url on an agent with no signing key returns a one-time webhook_signing_key for HMAC verification.

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

Auth types: hmac (default — HMAC-SHA256 signature) bearer (Authorization header) header (custom header name)

Payload formats: standard (raw JSON) openclaw (wrapped as { message, agentId, deliver })

GET/v1/webhooks/eventsList webhook delivery events▸

Browse recent webhook deliveries for your account. Agent-scoped keys auto-filter to their own events. Returns event type, delivery status, and timestamps.

Query Parameters
status — filter by delivery status: delivered pending failed
event_type — e.g. mail.mailed
agent_id — filter by agent (member keys only)
limit / offset — pagination (max 100)
Response · 200
{
  "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 }
}

Scope: webhook.read. Both sandbox and live events appear here.

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 (an address/package beta item, 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.

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.

v1.0 — live