Get Started

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.

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.
REST-only Cursor / LLM chat behavior

If a developer gives Cursor, Claude Code, or another LLM agent only an API key plus this /api-docs page, the agent can still answer billing and order-control questions over REST. Use the authenticated endpoints below with Authorization: Bearer sk_agent_...; MCP is optional.

How many credits do I have left?
GET /v1/credits
Read credits.balance_display and say the current prepaid balance. Mention that only the signed-in human can add funds at credits.billing_url.
Can I afford to send this?
POST /v1/mail with dry_run=true
Show credits_required_cents, cost_display, cost_breakdown, and human_review. If balance is low, compare it with GET /v1/credits before live submission.
Cancel this order
DELETE /v1/mail/:id
If status returns cancelled, report refunded_credits_cents, credit_balance_cents, and already_cancelled. If 409, say printing/mailing already started. If 5xx, poll mail status and credits before retrying; do not claim credits were returned until refund fields are present.
Order cancelled?
GET /v1/mail/:id
Read outbound_mail.status. If cancelled, say it is cancelled; if not, summarize the latest status, tracking/proof fields, and whether another cancellation attempt is still possible.
Sandbox
Test every endpoint and workflow with no credit debits. 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-credit-debit quote. Responses include human_review so CLI and chat agents can show the human the send-to address, return address, mail class, cost, document details, safeguards, and preview URL when available.

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_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"
What you can send
Letters and documents — invoices, notices, forms, statements, and document packets. Upload a PDF, DOCX, JPG, PNG, TXT, or CSV and it ships as USPS First-Class Mail, USPS Priority Mail, Certified Mail, FedEx, or UPS.
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.
Mail class guide for agents

Do not infer speed, tracking, or proof from carrier marketing names. Choose the enum by the required outcome, then use dry_run=true to compare authenticated cost before sending live mail.

mail_classServicePractical meaningTracking / proofAgent choice
first_classUSPS First-Class MailLowest-cost ordinary USPS letter mail. Standard letter mail; use for routine domestic business letters when speed/proof is not the goal.No carrier tracking number by default. mailbox.bot still records photo proof and status events.Do not choose this because the name sounds premium. It is the budget ordinary-letter option.
priorityUSPS Priority MailFaster USPS Priority Mail flat-rate envelope. Use when USPS is preferred and speed matters more than First-Class price.Includes USPS Tracking, but it is not Certified Mail proof.Choose for faster/tracked USPS delivery; choose certified instead when proof of mailing/delivery matters.
certifiedUSPS Certified MailUSPS Certified Mail. Use when the workflow requires USPS proof of mailing and delivery.Includes USPS tracking plus proof of mailing and delivery.Choose this when proof of mailing/delivery matters more than lowest cost or speed alone.
certified_return_receiptUSPS Certified Mail + Electronic Return ReceiptUSPS Certified Mail with Electronic Return Receipt. Use when the workflow needs stronger recipient evidence than Certified Mail alone.Includes certified tracking/proof plus electronic return-receipt evidence.Choose this when the workflow needs electronic return-receipt or recipient-signature evidence.
fedex_groundFedEx GroundBudget private-carrier ground delivery. Usually 1-5 business days depending on distance; not an Express service.Includes FedEx tracking.Choose when private-carrier tracking is wanted and cost matters more than speed.
fedex_expressFedEx Express SaverFedEx Express Saver. Third-business-day FedEx Express delivery in the normal domestic use case.Includes FedEx tracking.Despite the word Express, this is the slower/cheaper FedEx Express option compared with 2Day or Overnight.
fedex_2dayFedEx 2DayFedEx 2Day. Second-business-day FedEx delivery.Includes FedEx tracking.Choose when arrival in about two business days matters; it is faster than Express Saver.
fedex_overnightFedEx OvernightFedEx Overnight. Next-business-day FedEx delivery; not same-day courier service.Includes FedEx tracking.Choose only when next-business-day delivery is worth the higher price.
ups_groundUPS GroundBudget UPS ground delivery. Usually 1-5 business days depending on distance.Includes UPS tracking.Choose when UPS tracking is wanted and cost matters more than speed.
ups_2dayUPS 2nd Day AirUPS 2nd Day Air. Second-business-day UPS air delivery.Includes UPS tracking.Choose when arrival in about two business days matters.
ups_next_dayUPS Next Day AirUPS Next Day Air. Next-business-day UPS delivery; not same-day courier service.Includes UPS tracking.Choose only when next-business-day delivery is worth the higher price.
What happens after you hit send
1 Submitted — your document is validated (page count, dimensions, file size), cost is calculated from base per-page printing + postage + any additive color surcharge, and prepaid credits are debited before the facility queue. 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 service. USPS Priority Mail, Certified Mail, FedEx, and UPS require carrier-format tracking; USPS First-Class Mail may return tracking_number: null. Webhook: mail.mailed
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 fulfillment photos, available tracking info, and timestamps at each stage.

Transparent pricing
First-Class Mail special — a 1-page USPS First-Class Mail letter is priced at $1.00. Extra pages add base per-page printing and any additional postage from weight.
Per-page printing + handling — published default B&W printing is $0.30/page plus handling and postage. Color is an additional $0.40/page, so color pages are $0.70/page before handling and postage. These lines are shown separately in cost_breakdown.
Carrier postage estimate — calculated from page count, weight, destination ZIP, mail class, and the configured mailbox.bot fulfillment origin. FedEx/UPS service cards are base estimates by origin and destination zone/region; rate source appears in cost_breakdown.
Account pricing — public examples show the standard formula; plan or account-specific overrides are reflected in dashboard service cards, dry runs, sandbox estimates, and cost_breakdown.
Prepaid credits — live mail spends the human operator's mailbox.bot credits. Agents can read balance with GET /v1/credits but never access Stripe, card data, or Auto-Fill settings. Eligible agent orders may trigger bounded server-managed Auto-Fill only after the human separately enables it. Every response includes cost_cents, cost_display, credits_required_cents, and a full cost_breakdown.
Dry-run cost preview — send dry_run=true with your real document to get an exact cost breakdown without creating a record or spending credits. Use this to confirm pricing before committing.
Sandbox cost preview — test keys return estimated_live_cost_cents + cost_breakdown with no credit debit, 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 credit debit 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 — per-page printing + carrier postage estimate/rate 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, dispatch confirmations, delivery status, and simulated carrier-format tracking when the selected service includes tracking so your handlers exercise every lifecycle shape.
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, available 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-compatible agent harnesses, Hermes-style agents, A2A, and OpenClaw-compatible discovery. 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 credit debits, 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. Every endpoint is assigned automatically to Austin HQ; callers do not select 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, status webhooks, and tracking when the chosen service supports it are pushed back in real time.
Search existing mail: external agents can poll GET /v1/mail?q=... to find outbound mail by recipient name, address lines, city/state/ZIP, tracking number, or agent notes. Use created_after and created_before for submitted-date ranges, plus status, limit, and offset for polling pages. Agent-scoped keys only search that agent's own mail; member keys can search across agents and may pass test_mode=true or test_mode=false.
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
Billing: With a production key, POST /v1/mail spends the member's prepaid mailbox.bot credits. Agents never access Stripe, card data, or Auto-Fill settings; eligible orders may trigger bounded server-managed Auto-Fill only after human opt-in. Seven safeguards:
1. Balance read — call GET /v1/credits with billing.read or mail.send before live sends when balance may be low.
2. Cost cap — send X-Max-Cost-Cents: 1500 header. If the computed cost exceeds it, the request is rejected (422) before credits are spent — no record created, no facility work.
3. Dry run — send dry_run=true to validate your document and get an exact cost breakdown without creating a record or spending credits.
4. Approval flow — send requires_approval=true to create a pending review item with document_preview_url. No credits are spent until the member approves in their dashboard.
5. Test keys — use an sk_agent_test_ key during development. Identical flow, zero credit debits. Swap to a live key when ready.
6. Platform limits — per-transaction and daily spend limits are enforced server-side. If a debit would exceed either limit, the request is rejected (422) before credits are spent. Contact support if you need higher limits.
7. Duplicate and cancellation controls — recent exact or near-duplicate live submissions are rejected (409) before upload or credit debit. If a submitted item must be stopped before printing starts, call DELETE /v1/mail/:id or MCP cancel_outbound_mail; eligible credits are returned once.
Chat UX: Cursor and MCP agents should answer “How many credits do I have left?” with MCP get_usage; REST agents should call GET /v1/credits. Show balance_display, never try to buy credits as the agent, and direct top-ups to the human dashboard billing URL. For “cancel this order,” identify the outbound mail record, call the cancellation endpoint/tool while it is still submitted, then report status, returned credits, updated balance, and whether it was already cancelled.
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_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
Key fields:
document — supported formats: PDF, DOCX, JPG, PNG, TXT, CSV
recipient_name / recipient_company — provide a name, a company, or both; when both are present the company line prints between name and street address
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 (USPS First-Class Mail, ordinary letter, no carrier tracking by default), priority (USPS Priority Mail with USPS Tracking, not Certified Mail proof; $15.00 one-page floor), certified ($20.00 one-page floor), certified_return_receipt (Certified + Electronic Return Receipt; $24.00 one-page floor), fedex_ground, fedex_express (FedEx Express Saver, usually third business day), fedex_2day, fedex_overnight, ups_ground, ups_2day, ups_next_day
color — true for color printing (+$0.40/page on top of $0.30/page B&W; $0.70/page color total before handling and postage)
requires_approval — true to require member dashboard approval before printing (no credits spent 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
mail_run_id — optional explicit Business run opened with POST /v1/mail-runs; holds this live child outside fulfillment until one atomic run commit, and cannot be combined with dry run or per-piece approval
dry_run — true to validate and get cost breakdown without creating a record or spending credits
metadata — JSON object echoed in every response and webhook payload
Response always includes cost_breakdown with line-item detail: base printing per page, additive color surcharge per page, color page total when applicable, postage/rate source, zone, and private-carrier origin/base estimate fields. Dry-run and submission responses also include credits_required_cents and human_review for agent/human confirmation. Funded submission responses include credit_balance_cents. Submission responses include document metadata and document_preview_url; pdf_url is only populated for actual PDFs.
// Dry-run response (200) - no record and no credit debit
{
  "cost_cents": 2579,
  "cost_display": "$25.79",
  "credits_required_cents": 2579,
  "cost_breakdown": {
    "handling_cents": 250,
    "printing_cents": 180,
    "printing_per_page_cents": 30,
    "postage_cents": 2149,
    "postage_description": "Certified + Electronic 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 (insufficient prepaid credits; response includes INSUFFICIENT_CREDITS, credits_required_cents, credit_balance_cents, credit_shortfall_cents, billing_url ending in #credits, and suggested_action) · 404 (no active mailbox) · 409 (MAILBOX.md version mismatch or duplicate protection — no credits spent; duplicate responses include code: DUPLICATE_OUTBOUND_MAIL and details.existing_outbound_mail_id) · 503 (duplicate or idempotency protection temporarily unavailable — retryable, no credits spent) · 422 (cost exceeds X-Max-Cost-Cents, per-transaction limit, or daily spend cap — no credits spent)
// Insufficient credits response (402)
{
  "error": "Insufficient credits. This mail requires $25.79 and your balance is $8.42.",
  "retryable": false,
  "code": "INSUFFICIENT_CREDITS",
  "billing_url": "https://mailbox.bot/dashboard/billing#credits",
  "credits_required_cents": 2579,
  "credit_balance_cents": 842,
  "credit_shortfall_cents": 1737,
  "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

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.

Support Tickets

Authenticated agents and CLI tools can open support conversations on behalf of the mailbox renter. Use this when the human asks the agent to contact mailbox.bot support, or when an API, MCP, outbound-mail, billing, account, carrier, MAILBOX.md, Form 1583, notary, inbound-context, package, or managed-address issue needs mailbox.bot review. Agent keys need message.send. Full agent guidance lives in llms-full.txt.
POST/v1/messagesOpen a support ticket▸
Request
{
  "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."
}

Categories: billing support feature account other. Include the human request verbatim, relevant mailbox.bot IDs, and whether the human authorized the agent to send the ticket.

Use conversation_id for follow-up reads, replies, and attachments. New ticket intake is limited to 3 active unresolved tickets and 3 new tickets per rolling 24 hours per member.

Response · 201
{
  "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

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 spending credits. The sandbox validates your document, calculates postage, fires HMAC-signed webhooks, and simulates the complete facility fulfillment workflow — including proof-of-fulfillment photos, dispatch confirmations, and simulated carrier-format tracking when the selected service includes tracking — so your integration handles status changes 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. GET /v1/mail?q=... searches sandbox records by default for test keys, and live records by default for live agent keys; pass test_mode=true to explicitly list/search sandbox records. 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 credit debit — the response includes cost_cents: 0 plus estimated_live_cost_cents showing production cost with a full cost_breakdown (base printing, postage/rate source, additive color surcharge, and private-carrier origin/zone fields when applicable).
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 facility work: fulfillment photos, dispatch method, and test tracking for tracked services. 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 credit debit, 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
Creditscost_cents: 0Prepaid credit debit
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 spending credits. Works with any key.
X-Max-Cost-Cents — set this header to a cap (e.g. 5000) and the request rejects with 422 before credits are spent 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, REST API, and custom agent harnesses.

v1.0 — live